commitrocket 0.1.1__py3-none-any.whl

commitrocket/config.py

@@ -0,0 +1,125 @@
+import tomllib
+from pathlib import Path
+
+from commitrocket.errors import CommitRocketError
+
+CONFIG_NAME = "commitrocket.toml"
+PYPROJECT_NAME = "pyproject.toml"
+
+# Options that make no sense in a config file.
+NOT_CONFIGURABLE = {"config", "repo", "help", "version"}
+
+# Options an untrusted (repository) config file must not set: they can skip the
+# confirmation, push to another remote, write files, send data to a URL or read
+# files. They work in a file passed explicitly with --config.
+SENSITIVE_KEYS = {
+    "force",
+    "remote",
+    "branch",
+    "report",
+    "log_file",
+    "notify_webhook",
+    "include_from",
+    "exclude_from",
+}
+
+
+class ConfigError(CommitRocketError):
+    """The config file could not be read or holds an invalid value."""
+
+
+def find_config(repo, explicit=None):
+    """Return (path, values) from the config file, or (None, {}) if there is none.
+
+    Looked up in the repository folder: commitrocket.toml first, then the
+    [tool.commitrocket] table of pyproject.toml. --config overrides the lookup.
+    """
+    if explicit:
+        path = Path(explicit).expanduser()
+        if not path.is_file():
+            raise ConfigError(f"Config file not found: {path}")
+        return path, _load(path)
+
+    folder = Path(repo).expanduser()
+    plain = folder / CONFIG_NAME
+    if plain.is_file():
+        return plain, _load(plain)
+
+    pyproject = folder / PYPROJECT_NAME
+    if pyproject.is_file():
+        values = _load(pyproject)
+        if values:
+            return pyproject, values
+
+    return None, {}
+
+
+def _load(path):
+    try:
+        with open(path, "rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"Cannot read config file {path}: {exc}") from exc
+
+    if path.name == PYPROJECT_NAME:
+        data = data.get("tool", {}).get("commitrocket", {})
+    return data
+
+
+def apply_config(parser, values, source, trusted=False):
+    """Use config values as the parser's defaults, so the command line wins.
+
+    A config file found in the repository is untrusted: anyone who can change the
+    repository can change it. Unless trusted (the user named it with --config),
+    settings that can skip the confirmation, push elsewhere, write files or contact
+    other servers are ignored. Returns the names of the ignored settings.
+    """
+    actions = {action.dest: action for action in parser._actions}
+    defaults = {}
+    ignored = []
+
+    for key, value in values.items():
+        dest = key.replace("-", "_")
+        action = actions.get(dest)
+        if action is None or dest in NOT_CONFIGURABLE:
+            raise ConfigError(f"{source}: unknown option '{key}'")
+        coerced = _coerce(action, key, value, source)
+        if dest in SENSITIVE_KEYS and not trusted:
+            ignored.append(key)
+        else:
+            defaults[dest] = coerced
+
+    parser.set_defaults(**defaults)
+    return ignored
+
+
+def _coerce(action, key, value, source):
+    where = f"{source}: '{key}'"
+
+    if action.nargs == 0:  # a flag such as --force
+        if not isinstance(value, bool):
+            raise ConfigError(f"{where} must be true or false")
+        return value
+
+    if _is_append(action):
+        if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+            raise ConfigError(f"{where} must be a list of strings")
+        return value
+
+    if isinstance(value, (bool, list, dict)):
+        raise ConfigError(f"{where} has the wrong type")
+
+    if action.type is not None:
+        try:
+            value = action.type(value)
+        except (TypeError, ValueError) as exc:
+            raise ConfigError(f"{where} is invalid: {exc}") from exc
+
+    if action.choices and value not in action.choices:
+        choices = ", ".join(map(str, action.choices))
+        raise ConfigError(f"{where} must be one of: {choices}")
+    return value
+
+
+def _is_append(action):
+    return type(action).__name__ == "_AppendAction"

commitrocket/doctor.py

@@ -0,0 +1,202 @@
+import logging
+import subprocess
+import sys
+from pathlib import Path
+
+from rich.table import Table
+from rich.text import Text
+
+from commitrocket.batching import MIB
+from commitrocket.config import ConfigError, find_config
+from commitrocket.errors import CommitRocketError, GitError
+from commitrocket.filters import IGNORE_FILE
+from commitrocket.git import (
+    find_large_unpushed_blobs,
+    get_file_size,
+    get_pending_files,
+    get_staged_files,
+    get_unpushed_commits,
+    resolve_target,
+    run_git,
+)
+from commitrocket.journal import Journal
+from commitrocket.lfs import HOST_LIMIT_MIB, is_lfs_available
+from commitrocket.logs import default_log_dir
+from commitrocket.security import redact
+
+logger = logging.getLogger(__name__)
+
+PASS, WARN, FAIL, SKIP = "pass", "warn", "fail", "skip"
+STYLES = {PASS: "green", WARN: "yellow", FAIL: "bold red", SKIP: "dim"}
+NETWORK_TIMEOUT = 60
+
+
+def _first_line(text):
+    lines = [line for line in text.strip().splitlines() if line.strip()]
+    return redact(lines[0]) if lines else "no details"
+
+
+def _remote_check(repo, args, label):
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo), *args],
+            text=True,
+            capture_output=True,
+            timeout=NETWORK_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        return FAIL, f"{label} timed out after {NETWORK_TIMEOUT} s"
+    if result.returncode != 0:
+        return FAIL, _first_line(result.stderr or result.stdout)
+    return PASS, label
+
+
+def _check_log_dir():
+    folder = default_log_dir()
+    try:
+        folder.mkdir(parents=True, exist_ok=True)
+        probe = folder / ".doctor-probe"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+    except OSError as exc:
+        return WARN, f"{folder} is not writable ({exc})"
+    return PASS, str(folder)
+
+
+def collect_checks(repo, remote=None, branch=None, offline=False, config_path=None):
+    """Run every check and return [(status, name, detail), ...]."""
+    results = []
+
+    def add(status, name, detail):
+        results.append((status, name, detail))
+        logger.info("doctor: %s %s - %s", status, name, detail)
+
+    add(PASS, "Python", sys.version.split()[0])
+
+    try:
+        git_version = subprocess.run(
+            ["git", "--version"], text=True, stdout=subprocess.PIPE
+        ).stdout.strip()
+    except OSError:
+        add(FAIL, "Git", "git was not found on PATH")
+        return results
+    add(PASS, "Git", git_version)
+
+    if is_lfs_available():
+        add(PASS, "git-lfs", "installed")
+    else:
+        add(WARN, "git-lfs", "not installed (needed only for --use-lfs)")
+
+    try:
+        path, values = find_config(repo, config_path)
+        detail = f"{path} ({len(values)} setting(s))" if path else "none (defaults)"
+        add(PASS, "Config file", detail)
+    except ConfigError as exc:
+        add(FAIL, "Config file", str(exc))
+
+    status, detail = _check_log_dir()
+    add(status, "Log folder", detail)
+
+    try:
+        root = Path(run_git(repo, "rev-parse", "--show-toplevel").stdout.strip())
+    except (GitError, OSError):
+        add(FAIL, "Repository", f"{repo} is not inside a Git repository")
+        return results
+    add(PASS, "Repository", str(root))
+
+    local_branch = run_git(root, "branch", "--show-current").stdout.strip()
+    if not local_branch:
+        add(FAIL, "Branch", "detached HEAD; check out a branch")
+        return results
+    add(PASS, "Branch", local_branch)
+
+    try:
+        target = resolve_target(root, local_branch, remote, branch)
+    except CommitRocketError as exc:
+        add(FAIL, "Push target", str(exc))
+        return results
+    add(PASS, "Push target", target.label)
+
+    if offline:
+        add(SKIP, "Remote access", "skipped (--offline)")
+        add(SKIP, "Push permission", "skipped (--offline)")
+    else:
+        status, detail = _remote_check(
+            root, ["ls-remote", "--", target.remote, "HEAD"], "remote reachable"
+        )
+        add(status, "Remote access", detail)
+        status, detail = _remote_check(
+            root,
+            ["push", "--dry-run", "--", target.remote, target.refspec],
+            "push accepted (dry run)",
+        )
+        add(WARN if status == FAIL else status, "Push permission", detail)
+
+    staged = get_staged_files(root)
+    entry = Journal(root).read()
+    if staged and not (entry and set(staged) <= set(entry["files"])):
+        add(WARN, "Staged files", f"{len(staged)} file(s) staged; the run would stop")
+    elif staged:
+        add(PASS, "Staged files", f"{len(staged)} file(s) left by an interrupted run")
+    else:
+        add(PASS, "Staged files", "none")
+
+    try:
+        unpushed = get_unpushed_commits(root, target.revs)
+        large = find_large_unpushed_blobs(root, HOST_LIMIT_MIB * MIB, target.revs)
+    except GitError:
+        add(WARN, "Unpushed commits", "could not be inspected (no commits yet?)")
+    else:
+        if large:
+            add(
+                WARN,
+                "Unpushed commits",
+                f"{len(unpushed)} commit(s) contain files over "
+                f"{HOST_LIMIT_MIB} MiB; run 'git reset --mixed {target.label}'",
+            )
+        else:
+            add(PASS, "Unpushed commits", f"{len(unpushed)} (will be pushed first)")
+
+    ignore = root / IGNORE_FILE
+    add(PASS, IGNORE_FILE, "present" if ignore.is_file() else "not used")
+
+    pending = get_pending_files(root)
+    big = [p for p in pending if get_file_size(root, p) > HOST_LIMIT_MIB * MIB]
+    if big:
+        add(
+            WARN,
+            "Pending files",
+            f"{len(pending)} file(s), {len(big)} over {HOST_LIMIT_MIB} MiB "
+            "(use --use-lfs)",
+        )
+    else:
+        add(PASS, "Pending files", f"{len(pending)} file(s)")
+
+    return results
+
+
+def run_doctor(
+    console, repo, remote=None, branch=None, offline=False, config_path=None
+):
+    """Print a health report. Returns 1 if any check failed, else 0."""
+    results = collect_checks(repo, remote, branch, offline, config_path)
+
+    table = Table(title="CommitRocket doctor", show_lines=False)
+    table.add_column("Status")
+    table.add_column("Check")
+    table.add_column("Details", overflow="fold")
+    for status, name, detail in results:
+        label = f"[{STYLES[status]}]{status.upper()}[/]"
+        table.add_row(label, Text(name), Text(detail))
+    console.print(table)
+
+    failed = [name for status, name, _ in results if status == FAIL]
+    warned = [name for status, name, _ in results if status == WARN]
+    if failed:
+        console.print(f"\n[bold red]{len(failed)} check(s) failed.[/bold red]")
+        return 1
+    if warned:
+        console.print(f"\n[yellow]OK with {len(warned)} warning(s).[/yellow]")
+    else:
+        console.print("\n[bold green]All checks passed.[/bold green]")
+    return 0

commitrocket/errors.py

@@ -0,0 +1,14 @@
+class CommitRocketError(RuntimeError):
+    """Base class for expected, user-reportable failures."""
+
+
+class GitError(CommitRocketError):
+    """A git command failed."""
+
+
+class PushError(GitError):
+    """A git push failed. retryable is False when trying again cannot help."""
+
+    def __init__(self, message, retryable=True):
+        super().__init__(message)
+        self.retryable = retryable

commitrocket/eta.py

@@ -0,0 +1,40 @@
+import time
+
+# Wait for this much real upload time before trusting the measured speed.
+MIN_SECONDS = 5.0
+
+
+def format_duration(seconds):
+    seconds = max(0, int(seconds))
+    hours, remainder = divmod(seconds, 3600)
+    minutes, secs = divmod(remainder, 60)
+    return f"{hours}:{minutes:02d}:{secs:02d}"
+
+
+class EtaEstimator:
+    """ETA from the average speed of the whole run so far.
+
+    Speed is bytes completed (including the part of the current batch already
+    uploaded) divided by the time since the first batch started, so per-batch
+    overhead such as `git add`, commit and push handshakes is included.
+    """
+
+    def __init__(self, clock=time.monotonic):
+        self.clock = clock
+        self.started_at = None
+
+    def start(self):
+        if self.started_at is None:
+            self.started_at = self.clock()
+
+    def estimate(self, done_bytes, total_bytes):
+        """Seconds remaining, or None while there is not enough data yet."""
+        if self.started_at is None or done_bytes <= 0:
+            return None
+
+        elapsed = self.clock() - self.started_at
+        if elapsed < MIN_SECONDS:
+            return None
+
+        remaining = max(0, total_bytes - done_bytes)
+        return remaining / (done_bytes / elapsed)

commitrocket/filters.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+
+import pathspec
+
+from commitrocket.errors import CommitRocketError
+
+IGNORE_FILE = ".commitrocketignore"
+
+
+def read_patterns(path):
+    """Pattern lines from a file; blank lines and # comments are skipped."""
+    try:
+        text = Path(path).expanduser().read_text(encoding="utf-8")
+    except OSError as exc:
+        raise CommitRocketError(f"Cannot read pattern file {path}: {exc}") from exc
+
+    return [
+        line.strip()
+        for line in text.splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    ]
+
+
+def _spec(lines):
+    try:
+        return pathspec.PathSpec.from_lines("gitignore", lines)
+    except KeyError:
+        # pathspec before 1.0 only knows the older name for the same syntax.
+        return pathspec.PathSpec.from_lines("gitwildmatch", lines)
+
+
+class FileFilter:
+    """Keep only the files that match --include (if any) and not --exclude.
+
+    Patterns use .gitignore syntax: '*.mp4' matches at any depth, 'raw/' a
+    folder, '/notes.txt' only at the repo root, '**' any number of folders.
+    Exclusion always wins over inclusion.
+    """
+
+    def __init__(self, include=(), exclude=()):
+        self.include = _spec(include) if include else None
+        self.exclude = _spec(exclude) if exclude else None
+
+    @classmethod
+    def from_options(cls, repo, include, exclude, include_from, exclude_from):
+        include_lines = list(include)
+        for path in include_from:
+            include_lines += read_patterns(path)
+
+        exclude_lines = list(exclude)
+        for path in exclude_from:
+            exclude_lines += read_patterns(path)
+
+        ignore_file = Path(repo) / IGNORE_FILE
+        if ignore_file.is_file():
+            exclude_lines += read_patterns(ignore_file)
+
+        return cls(include_lines, exclude_lines)
+
+    @property
+    def active(self):
+        return self.include is not None or self.exclude is not None
+
+    def keeps(self, path):
+        if self.exclude is not None and self.exclude.match_file(path):
+            return False
+        if self.include is not None and not self.include.match_file(path):
+            return False
+        return True
+
+    def apply(self, paths):
+        return [path for path in paths if self.keeps(path)]

commitrocket/git.py

@@ -0,0 +1,228 @@
+import logging
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from commitrocket.errors import CommitRocketError, GitError
+from commitrocket.security import redact, validate_ref_part
+
+logger = logging.getLogger(__name__)
+
+MAX_LOGGED_OUTPUT = 2000
+MAX_LOGGED_COMMAND = 500
+MAX_COMMAND_CHARS = 20000
+
+
+def _logged_output(result):
+    text = "\n".join(part for part in (result.stdout, result.stderr) if part.strip())
+    text = text.strip().replace("\0", "|")
+    if len(text) > MAX_LOGGED_OUTPUT:
+        text = text[:MAX_LOGGED_OUTPUT] + "... [truncated]"
+    return f"\n{text}" if text else ""
+
+
+def run_git(repo, *args, check=True):
+    result = subprocess.run(
+        ["git", "-C", str(repo), *args],
+        text=True,
+        capture_output=True,
+        # File names are literal: "[ab].txt" must not also match a.txt and b.txt.
+        env={**os.environ, "GIT_LITERAL_PATHSPECS": "1"},
+    )
+    command = _shortened(" ".join(args))
+    logger.debug(
+        "git %s -> exit %d%s", command, result.returncode, _logged_output(result)
+    )
+
+    if check and result.returncode != 0:
+        error = result.stderr.strip() or result.stdout.strip()
+        raise GitError(redact(f"git {command} failed:\n{error}"))
+
+    return result
+
+
+def _shortened(command):
+    """Keep logs and errors readable when a command lists thousands of files."""
+    if len(command) <= MAX_LOGGED_COMMAND:
+        return command
+    return command[:MAX_LOGGED_COMMAND] + "... [truncated]"
+
+
+def chunk_paths(paths, limit=MAX_COMMAND_CHARS):
+    """Split paths into groups that fit on one command line.
+
+    Windows allows about 32,767 characters for a whole command, so a batch with
+    thousands of files cannot be passed to git in one go. Each path is counted at
+    twice its length, to leave room for the quoting Windows adds.
+    """
+    chunk = []
+    size = 0
+    for path in paths:
+        cost = 2 * len(path) + 3
+        if chunk and size + cost > limit:
+            yield chunk
+            chunk = []
+            size = 0
+        chunk.append(path)
+        size += cost
+    if chunk:
+        yield chunk
+
+
+def add_files(repo, paths):
+    """Stage the given files, however many there are."""
+    for chunk in chunk_paths(paths):
+        run_git(repo, "add", "--", *chunk)
+
+
+def get_paths(repo, *args):
+    return [path for path in run_git(repo, *args).stdout.split("\0") if path]
+
+
+def get_staged_files(repo):
+    return get_paths(repo, "diff", "--cached", "--name-only", "-z")
+
+
+def get_pending_files(repo):
+    unstaged = get_paths(repo, "diff", "--name-only", "-z")
+    untracked = get_paths(repo, "ls-files", "--others", "--exclude-standard", "-z")
+    return list(dict.fromkeys(unstaged + untracked))
+
+
+class LocalConfig:
+    """Set repository-local Git config for a run and put the old values back.
+
+    Only the repo's own .git/config is touched, never the global config.
+    """
+
+    def __init__(self, repo):
+        self.repo = repo
+        self.saved = {}
+
+    def set(self, key, value):
+        if key not in self.saved:
+            current = run_git(self.repo, "config", "--local", "--get", key, check=False)
+            found = current.returncode == 0
+            self.saved[key] = current.stdout.strip() if found else None
+        run_git(self.repo, "config", "--local", key, str(value))
+
+    def restore(self):
+        for key, old in self.saved.items():
+            if old is None:
+                run_git(self.repo, "config", "--local", "--unset", key, check=False)
+            else:
+                run_git(self.repo, "config", "--local", key, old, check=False)
+        self.saved.clear()
+
+
+@dataclass
+class PushTarget:
+    """Where a run pushes to, and how to tell what is not there yet."""
+
+    remote: str
+    branch: str
+    revs: list
+
+    @property
+    def ref(self):
+        return f"refs/heads/{self.branch}"
+
+    @property
+    def refspec(self):
+        return f"HEAD:{self.ref}"
+
+    @property
+    def label(self):
+        """Display name for the target; safe to show, log, report and send."""
+        return redact(f"{self.remote}/{self.branch}")
+
+
+def resolve_target(repo, local_branch, remote=None, branch=None):
+    """The remote branch to push to: explicit values first, then the upstream."""
+    configured_remote = run_git(
+        repo, "config", "--get", f"branch.{local_branch}.remote", check=False
+    ).stdout.strip()
+    configured_merge = run_git(
+        repo, "config", "--get", f"branch.{local_branch}.merge", check=False
+    ).stdout.strip()
+
+    remote = remote or configured_remote
+    if not remote:
+        raise CommitRocketError(
+            "No upstream configured. Configure one, or pass --remote "
+            "(and optionally --branch)."
+        )
+
+    branch = branch or configured_merge.removeprefix("refs/heads/") or local_branch
+
+    # These end up on git command lines, so they must not look like options.
+    validate_ref_part(remote, "remote")
+    validate_ref_part(branch, "branch")
+
+    tracking_ref = f"refs/remotes/{remote}/{branch}"
+    exists = run_git(
+        repo, "rev-parse", "--verify", "--quiet", tracking_ref, check=False
+    ).returncode
+    if exists == 0:
+        revs = [f"{tracking_ref}..HEAD"]
+    else:
+        # The branch was never pushed to this remote: everything the remote
+        # does not already have counts as unpushed.
+        revs = ["HEAD", "--not", f"--remotes={remote}"]
+
+    return PushTarget(remote, branch, revs)
+
+
+def get_remote_url(repo, remote):
+    return run_git(repo, "remote", "get-url", "--", remote).stdout.strip()
+
+
+def get_remote_head(repo, remote, ref):
+    """Commit the remote currently has for ref, or None if it doesn't exist."""
+    fields = run_git(repo, "ls-remote", "--", remote, ref).stdout.split()
+    return fields[0] if fields else None
+
+
+def get_unpushed_commits(repo, revs):
+    """One-line summaries of local commits that are not on the remote yet."""
+    return run_git(repo, "log", "--oneline", *revs).stdout.splitlines()
+
+
+def find_large_unpushed_blobs(repo, threshold_bytes, revs):
+    """(path, size) of blobs above the threshold in commits not yet pushed."""
+    objects = run_git(repo, "rev-list", "--objects", *revs).stdout
+    if not objects.strip():
+        return []
+
+    result = subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repo),
+            "cat-file",
+            "--batch-check=%(objecttype) %(objectsize) %(rest)",
+        ],
+        input=objects,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        raise GitError(f"git cat-file failed:\n{result.stderr.strip()}")
+
+    large = {}
+    for line in result.stdout.splitlines():
+        kind, size, path = (line.split(" ", 2) + ["", ""])[:3]
+        if kind == "blob" and int(size) > threshold_bytes:
+            large[path or "(unnamed)"] = int(size)
+    return sorted(large.items())
+
+
+def get_file_size(repo, relative_path):
+    try:
+        path = Path(repo) / relative_path
+        return path.stat().st_size if path.is_file() else 0
+    except OSError:
+        return 0