commitguardian 0.1.0__py3-none-any.whl

commitguard/utils/filesystem.py

@@ -0,0 +1,72 @@
+"""Filesystem helpers with conservative defaults.
+
+* Reads are size-limited and only follow regular files.
+* Writes are atomic and never overwrite an existing file unless asked to.
+"""
+
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+from commitguard.exceptions.base import UnsafeInputError
+
+
+def read_bytes_limited(path: Path, *, max_bytes: int) -> bytes:
+    """Read a regular file, refusing files larger than ``max_bytes``.
+
+    Raises :class:`FileNotFoundError` if the file is missing and
+    :class:`UnsafeInputError` if it is not a regular file or is too large.
+    """
+    st = path.stat()  # follows symlinks deliberately; the target must be regular
+    if not stat.S_ISREG(st.st_mode):
+        raise UnsafeInputError(f"{path} is not a regular file")
+    if st.st_size > max_bytes:
+        raise UnsafeInputError(f"{path} is larger than {max_bytes} bytes")
+    with path.open("rb") as handle:
+        data = handle.read(max_bytes + 1)
+    if len(data) > max_bytes:  # file grew between stat() and read()
+        raise UnsafeInputError(f"{path} is larger than {max_bytes} bytes")
+    return data
+
+
+def read_text_limited(path: Path, *, max_bytes: int, encoding: str = "utf-8") -> str:
+    """Like :func:`read_bytes_limited`, decoding strictly as ``encoding``."""
+    data = read_bytes_limited(path, max_bytes=max_bytes)
+    try:
+        return data.decode(encoding)
+    except UnicodeDecodeError as exc:
+        raise UnsafeInputError(f"{path} is not valid {encoding} text") from exc
+
+
+def atomic_write_text(
+    path: Path,
+    content: str,
+    *,
+    overwrite: bool = False,
+    mode: int = 0o644,
+) -> None:
+    """Atomically write ``content`` to ``path``.
+
+    The data is written to a temporary file in the same directory and then
+    moved into place. With ``overwrite=False`` (the default) an existing file
+    is never replaced and :class:`FileExistsError` is raised.
+    """
+    directory = path.parent
+    fd, tmp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=directory)
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        tmp_path.chmod(mode)
+        if overwrite:
+            tmp_path.replace(path)
+        else:
+            # os.link fails atomically if the destination exists.
+            os.link(tmp_path, path)
+            tmp_path.unlink()
+    except BaseException:
+        tmp_path.unlink(missing_ok=True)
+        raise

commitguard/utils/platform.py

@@ -0,0 +1,35 @@
+"""Platform and runtime introspection."""
+
+import platform
+import sys
+
+MINIMUM_PYTHON = (3, 12)
+
+
+def python_version() -> str:
+    """Return the running interpreter version as ``X.Y.Z``."""
+    return platform.python_version()
+
+
+def python_version_supported() -> bool:
+    """Return True if the running interpreter meets :data:`MINIMUM_PYTHON`."""
+    return sys.version_info[:2] >= MINIMUM_PYTHON
+
+
+def is_windows() -> bool:
+    """Return True on Windows (affects hook scripts and executable bits)."""
+    return sys.platform.startswith("win")
+
+
+def path_for_posix_shell(path: str) -> str:
+    """Render a filesystem path for use inside a POSIX ``sh`` script.
+
+    Git for Windows runs hooks with its bundled ``sh``, which accepts
+    ``C:/Users/...`` style paths; backslashes would be escape characters.
+    """
+    return path.replace("\\", "/") if is_windows() else path
+
+
+def supports_executable_bit() -> bool:
+    """False on Windows, where Git decides executability from the ``#!`` line."""
+    return not is_windows()

commitguard/utils/subprocess.py

@@ -0,0 +1,84 @@
+"""Safe subprocess execution.
+
+Rules enforced here, for every external command CommitGuard runs:
+
+* commands are argument sequences, never shell strings (``shell=False``);
+* arguments must be ``str`` and must not contain NUL bytes;
+* stdin is closed unless input is explicitly supplied;
+* every call has a timeout;
+* the environment is inherited but can only be *extended* with explicit keys,
+  and is never logged.
+"""
+
+import os
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from commitguard.exceptions.base import UnsafeInputError
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    """Raw result of an external command. Output is kept as bytes."""
+
+    args: tuple[str, ...]
+    returncode: int
+    stdout: bytes
+    stderr: bytes
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+def run_command(
+    args: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    env_overrides: Mapping[str, str] | None = None,
+    input_bytes: bytes | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> CommandResult:
+    """Run an external command without a shell and capture its output.
+
+    Raises :class:`UnsafeInputError` for malformed argument vectors and lets
+    :class:`FileNotFoundError` / :class:`subprocess.TimeoutExpired` propagate so
+    callers can map them to domain errors.
+    """
+    if isinstance(args, str | bytes):
+        raise UnsafeInputError("command must be an argument sequence, not a string")
+    argv = tuple(args)
+    if not argv:
+        raise UnsafeInputError("command must not be empty")
+    for arg in argv:
+        if not isinstance(arg, str):
+            raise UnsafeInputError("command arguments must be strings")
+        if "\x00" in arg:
+            raise UnsafeInputError("command arguments must not contain NUL bytes")
+
+    env = dict(os.environ)
+    if env_overrides:
+        env.update(env_overrides)
+
+    # TODO(phase-2): cap captured output size for very large repositories.
+    completed = subprocess.run(  # noqa: S603 - argv is validated and shell=False
+        argv,
+        cwd=cwd,
+        env=env,
+        input=input_bytes,
+        stdin=None if input_bytes is not None else subprocess.DEVNULL,
+        capture_output=True,
+        timeout=timeout,
+        shell=False,
+        check=False,
+    )
+    return CommandResult(
+        args=argv,
+        returncode=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+    )