git-ember 1.2.0__py3-none-any.whl

gitember/colors.py

@@ -0,0 +1,143 @@
+RESET = "\x1b[0m"
+LIGHT_GRAY = "\x1b[38;5;250m"
+
+
+class ColorScheme:
+    """Color scheme with 5 intensity levels (0-4)."""
+
+    def __init__(self, name: str, levels: list[str]):
+        self.name = name
+        self.levels = levels
+
+    def get(self, level: int) -> str:
+        """Return ANSI code for intensity level 0-4."""
+        return self.levels[min(level, 4)]
+
+
+GREEN = ColorScheme(
+    "green",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey (no commits)
+        "\x1b[38;5;22m",  # 1: darker green
+        "\x1b[38;5;28m",  # 2: dark green
+        "\x1b[38;5;34m",  # 3: medium green
+        "\x1b[38;5;40m",  # 4: bright green
+    ],
+)
+
+BLUE = ColorScheme(
+    "blue",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;17m",  # 1: dark blue
+        "\x1b[38;5;19m",  # 2: blue
+        "\x1b[38;5;21m",  # 3: bright blue
+        "\x1b[38;5;33m",  # 4: brightest blue
+    ],
+)
+
+ORANGE = ColorScheme(
+    "orange",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;130m",  # 1: dark orange
+        "\x1b[38;5;166m",  # 2: orange
+        "\x1b[38;5;208m",  # 3: bright orange
+        "\x1b[38;5;214m",  # 4: brightest orange
+    ],
+)
+
+PURPLE = ColorScheme(
+    "purple",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;54m",  # 1: dark purple
+        "\x1b[38;5;92m",  # 2: purple
+        "\x1b[38;5;129m",  # 3: bright purple
+        "\x1b[38;5;141m",  # 4: brightest purple
+    ],
+)
+
+MONO = ColorScheme(
+    "mono",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;235m",  # 1: dark grey
+        "\x1b[38;5;240m",  # 2: grey
+        "\x1b[38;5;250m",  # 3: light grey
+        "\x1b[38;5;255m",  # 4: white
+    ],
+)
+
+RED = ColorScheme(
+    "red",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;52m",  # 1: dark red
+        "\x1b[38;5;124m",  # 2: red
+        "\x1b[38;5;160m",  # 3: bright red
+        "\x1b[38;5;196m",  # 4: brightest red
+    ],
+)
+
+YELLOW = ColorScheme(
+    "yellow",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;58m",  # 1: dark yellow
+        "\x1b[38;5;100m",  # 2: olive
+        "\x1b[38;5;178m",  # 3: yellow
+        "\x1b[38;5;226m",  # 4: bright yellow
+    ],
+)
+
+TEAL = ColorScheme(
+    "teal",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;23m",  # 1: dark teal
+        "\x1b[38;5;29m",  # 2: teal
+        "\x1b[38;5;37m",  # 3: bright teal
+        "\x1b[38;5;45m",  # 4: brightest teal
+    ],
+)
+
+PINK = ColorScheme(
+    "pink",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;125m",  # 1: dark pink
+        "\x1b[38;5;169m",  # 2: pink
+        "\x1b[38;5;183m",  # 3: bright pink
+        "\x1b[38;5;219m",  # 4: brightest pink
+    ],
+)
+
+AQUA = ColorScheme(
+    "aqua",
+    [
+        "\x1b[38;5;234m",  # 0: dark grey
+        "\x1b[38;5;30m",  # 1: dark aqua
+        "\x1b[38;5;37m",  # 2: aqua
+        "\x1b[38;5;38m",  # 3: bright aqua
+        "\x1b[38;5;51m",  # 4: brightest aqua
+    ],
+)
+
+COLOR_SCHEMES = {
+    "green": GREEN,
+    "blue": BLUE,
+    "orange": ORANGE,
+    "purple": PURPLE,
+    "red": RED,
+    "yellow": YELLOW,
+    "teal": TEAL,
+    "pink": PINK,
+    "aqua": AQUA,
+    "mono": MONO,
+}
+
+
+def get_color_scheme(name: str) -> ColorScheme:
+    """Get color scheme by name, defaulting to green."""
+    return COLOR_SCHEMES.get(name, GREEN)

gitember/git.py

@@ -0,0 +1,535 @@
+import datetime as dt
+import subprocess
+from collections import Counter
+from typing import Any, Dict, List, Tuple
+import re
+
+COMMIT_PREFIX = "COMMIT:"
+
+
+def _validate_path(path: str) -> None:
+    """Validate path doesn't contain git options or special characters.
+
+    Raises:
+        ValueError: If path is invalid.
+    """
+    if not path:
+        raise ValueError("Path cannot be empty")
+
+    if path.startswith("-"):
+        raise ValueError(f"Invalid path: {path}")
+
+    if re.search(r"[;&|`$()]", path):
+        raise ValueError(f"Invalid characters in path: {path}")
+
+
+def _validate_branch(branch: str) -> None:
+    """Validate branch name doesn't contain git options or special characters.
+
+    Raises:
+        ValueError: If branch name is invalid.
+    """
+    if not branch:
+        raise ValueError("Branch name cannot be empty")
+
+    if branch.startswith("-"):
+        raise ValueError(f"Invalid branch name: {branch}")
+
+    if re.search(r"[;&|`$()]", branch):
+        raise ValueError(f"Invalid characters in branch name: {branch}")
+
+
+def _build_log_args(branch: str | None, repo_path: str) -> List[str]:
+    """Build git log arguments for branch filtering.
+
+    Args:
+        branch: Optional branch name to filter by.
+        repo_path: Path to git repository.
+
+    Returns:
+        List of git log arguments (may be empty).
+    """
+    if not branch:
+        return ["--all"]
+
+    default_branch = get_default_branch(repo_path)
+    if branch != default_branch:
+        return [branch, "--not", default_branch]
+    return [branch]
+
+
+def run_git_log(
+    start_date: dt.date,
+    end_date: dt.date,
+    repo_path: str,
+    branch: str | None = None,
+) -> Dict[dt.date, int]:
+    """Get commit counts per day within a date range.
+
+    Args:
+        start_date: Start of date range (inclusive).
+        end_date: End of date range (inclusive).
+        repo_path: Path to git repository.
+        branch: Optional branch name to filter by. Defaults to all branches.
+
+    Returns:
+        Dict mapping date to commit count.
+
+    Raises:
+        ValueError: If path is not a git repository.
+    """
+    _validate_path(repo_path)
+
+    if branch:
+        _validate_branch(branch)
+
+    try:
+        subprocess.run(
+            ["git", "-C", repo_path, "rev-parse", "--is-inside-work-tree"],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except subprocess.CalledProcessError:
+        raise ValueError(f"Not a git repository: {repo_path}")
+
+    since = start_date.isoformat()
+    until = end_date.isoformat()
+
+    cmd = [
+        "git",
+        "-C",
+        repo_path,
+        "log",
+    ]
+
+    cmd.extend(_build_log_args(branch, repo_path))
+
+    cmd.extend(
+        [
+            f"--since={since}",
+            f"--until={until}",
+            "--date=short",
+            "--pretty=%ad",
+        ]
+    )
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        err = result.stderr.strip() or result.stdout.strip()
+        raise ValueError(err or f"git log failed for {repo_path}")
+
+    counter: Counter = Counter()
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            y, m, d = map(int, line.split("-"))
+            counter[dt.date(y, m, d)] += 1
+        except (ValueError, IndexError):
+            continue
+    return dict(counter)
+
+
+def get_branches(repo_path: str) -> List[str]:
+    """Get list of local branch names.
+
+    Args:
+        repo_path: Path to git repository.
+
+    Returns:
+        List of branch names.
+    """
+    _validate_path(repo_path)
+
+    result = subprocess.run(
+        ["git", "-C", repo_path, "branch", "--format=%(refname:short)"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        return []
+
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def get_default_branch(repo_path: str) -> str:
+    """Get the default branch name (e.g., main, master).
+
+    Args:
+        repo_path: Path to git repository.
+
+    Returns:
+        Name of default branch, or "main" as fallback.
+    """
+    _validate_path(repo_path)
+
+    # Check common default branch names in order of popularity
+    for branch in ["main", "master", "origin/main", "origin/master"]:
+        result = subprocess.run(
+            ["git", "-C", repo_path, "rev-parse", "--verify", f"refs/heads/{branch}"],
+            capture_output=True,
+        )
+        if result.returncode == 0:
+            return branch
+
+    # Fallback: get current HEAD branch if it's not main/master
+    result = subprocess.run(
+        ["git", "-C", repo_path, "symbolic-ref", "refs/heads/HEAD"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        current = result.stdout.strip().replace("refs/heads/", "")
+        if current not in ["main", "master"]:
+            return current
+
+    # Ultimate fallback for bare repos or unusual setups
+    return "main"
+
+
+def get_recent_commits(
+    repo_path: str, count: int = 5, branch: str | None = None
+) -> List[Dict[str, str]]:
+    """Get recent commits with metadata.
+
+    Args:
+        repo_path: Path to git repository.
+        count: Number of commits to retrieve.
+        branch: Optional branch name to filter by.
+
+    Returns:
+        List of dicts with keys: hash, author, date, timestamp, message.
+    """
+    _validate_path(repo_path)
+
+    if branch:
+        _validate_branch(branch)
+
+    cmd = [
+        "git",
+        "-C",
+        repo_path,
+        "log",
+        f"-{count}",
+        "--pretty=format:%h|%an|%ad %at|%s",
+        "--date=short",
+    ]
+    cmd.extend(_build_log_args(branch, repo_path))
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        return []
+
+    commits = []
+    for line in result.stdout.splitlines():
+        if not line:
+            continue
+        parts = line.split("|", 3)
+        if len(parts) == 4:
+            datetime_parts = parts[2].rsplit(" ", 1)
+            date = datetime_parts[0]
+            timestamp = datetime_parts[1] if len(datetime_parts) > 1 else ""
+            commits.append(
+                {
+                    "hash": parts[0],
+                    "author": parts[1],
+                    "date": date,
+                    "timestamp": timestamp,
+                    "message": parts[3],
+                }
+            )
+    return commits
+
+
+def get_top_contributors(
+    repo_path: str, limit: int = 10, branch: str | None = None
+) -> List[Tuple[str, int]]:
+    """Get top contributors by commit count.
+
+    Args:
+        repo_path: Path to git repository.
+        limit: Maximum number of contributors to return.
+        branch: Optional branch name to filter by.
+
+    Returns:
+        List of (author, commit_count) tuples, sorted by count descending.
+    """
+    _validate_path(repo_path)
+
+    if branch:
+        _validate_branch(branch)
+
+    cmd = [
+        "git",
+        "-C",
+        repo_path,
+        "shortlog",
+        "-s",
+        "-n",
+    ]
+    cmd.extend(_build_log_args(branch, repo_path))
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        return []
+
+    contributors = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split(None, 1)
+        if len(parts) == 2:
+            try:
+                count = int(parts[0])
+                contributors.append((parts[1], count))
+            except ValueError:
+                continue
+    return contributors[:limit]
+
+
+def get_repo_stats(repo_path: str, branch: str | None = None) -> Dict[str, Any]:
+    """Get repository statistics.
+
+    Args:
+        repo_path: Path to git repository.
+        branch: Optional branch name to filter by.
+
+    Returns:
+        Dict with keys: total_commits, num_authors, first_commit_date,
+        first_commit_timestamp, last_commit_date, last_commit_timestamp.
+    """
+    _validate_path(repo_path)
+
+    if branch:
+        _validate_branch(branch)
+
+    log_args = _build_log_args(branch, repo_path)
+
+    result = subprocess.run(
+        [
+            "git",
+            "-C",
+            repo_path,
+            "log",
+            "--format=%an|%at|%ad",
+            "--date=format:%d-%m-%Y %H:%M",
+        ]
+        + log_args,
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        err = result.stderr.strip() or result.stdout.strip()
+        raise ValueError(err or f"git log failed for {repo_path}")
+
+    first_commit_timestamp = 0
+    first_commit_date = ""
+    last_commit_timestamp = ""
+    last_commit_date = ""
+    authors: set[str] = set()
+    total_commits = 0
+
+    for line in result.stdout.splitlines():
+        if not line:
+            continue
+        total_commits += 1
+        parts = line.split("|")
+        if len(parts) < 3:
+            continue
+
+        author, timestamp, date = parts[0], parts[1], parts[2]
+        authors.add(author)
+
+        ts = int(timestamp) if timestamp.isdigit() else 0
+        if ts:
+            if first_commit_timestamp == 0 or ts < first_commit_timestamp:
+                first_commit_timestamp = ts
+                first_commit_date = date
+            if not last_commit_timestamp or ts > int(last_commit_timestamp):
+                last_commit_timestamp = str(ts)
+                last_commit_date = date
+
+    return {
+        "total_commits": total_commits,
+        "num_authors": len(authors),
+        "first_commit_date": first_commit_date,
+        "first_commit_timestamp": first_commit_timestamp,
+        "last_commit_date": last_commit_date,
+        "last_commit_timestamp": last_commit_timestamp,
+    }
+
+
+def get_streaks(counts: Dict[dt.date, int]) -> Dict[str, Any]:
+    """Calculate current and longest streaks from commit counts.
+
+    Args:
+        counts: Dict mapping date to commit count.
+
+    Returns:
+        Dict with current_streak, longest_streak, longest_streak_end.
+    """
+    if not counts:
+        return {"current_streak": 0, "longest_streak": 0, "longest_streak_end": None}
+
+    sorted_dates = sorted(counts.keys())
+
+    longest = 0
+    longest_end = None
+    streak = 0
+    prev_date = None
+
+    for date in sorted_dates:
+        if prev_date is not None and (date - prev_date).days != 1:
+            streak = 0
+
+        if counts[date] > 0:
+            streak += 1
+            if streak >= longest:
+                longest = streak
+                longest_end = date
+        else:
+            streak = 0
+
+        prev_date = date
+
+    today = dt.date.today()
+    current = 0
+    for i in range(30):
+        check_date = today - dt.timedelta(days=i)
+        if check_date in counts and counts[check_date] > 0:
+            current += 1
+        else:
+            break
+
+    return {
+        "current_streak": current,
+        "longest_streak": longest,
+        "longest_streak_end": longest_end,
+    }
+
+
+def _parse_graph_line(line: str) -> tuple[str, str]:
+    """Extract the graph prefix and content from a git log line.
+
+    Args:
+        line: Raw line from git log --graph output.
+
+    Returns:
+        Tuple of (graph_line, content) where graph_line contains
+        the graph characters (|, /, \, *, spaces) and content is
+        the remaining text after the graph prefix.
+    """
+    graph_line = ""
+    idx = 0
+    while idx < len(line):
+        c = line[idx]
+        if c in "*|/\\":
+            graph_line += c
+            idx += 1
+            while idx < len(line) and line[idx] == " ":
+                graph_line += line[idx]
+                idx += 1
+        elif c == " " and graph_line:
+            graph_line += c
+            idx += 1
+        else:
+            break
+
+    content = line[idx:].lstrip()
+    return graph_line, content
+
+
+def get_branch_tree(
+    repo_path: str, branch: str | None = None, limit: int = 20
+) -> List[Dict[str, Any]]:
+    """Get branch tree data for visualization.
+
+    Args:
+        repo_path: Path to git repository.
+        branch: Optional branch name to filter by.
+        limit: Maximum number of commits to return.
+
+    Returns:
+        List of dicts with keys: hash, message, date, branches, graph_line.
+        Connector-only rows (/, \\ lines) are included with an empty hash
+        so the renderer can display branch split/merge lines correctly.
+    """
+    _validate_path(repo_path)
+
+    if branch:
+        _validate_branch(branch)
+
+    log_args = _build_log_args(branch, repo_path)
+
+    cmd = (
+        [
+            "git",
+            "-C",
+            repo_path,
+            "log",
+            "--format=COMMIT:%H|%h|%s|%d",
+            "--graph",
+            "--all",
+        ]
+        + log_args
+        + [f"-{limit}"]
+    )
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        return []
+
+    commits = []
+    for line in result.stdout.splitlines():
+        if not line:
+            continue
+
+        graph_line, content = _parse_graph_line(line)
+
+        if not content.startswith(COMMIT_PREFIX):
+            if graph_line:
+                commits.append(
+                    {
+                        "hash": "",
+                        "message": "",
+                        "branches": [],
+                        "graph_line": graph_line,
+                    }
+                )
+            continue
+
+        content = content[len(COMMIT_PREFIX) :]
+        parts = content.split("|")
+
+        if len(parts) >= 3:
+            hash7 = parts[1]
+            message = parts[2]
+
+            branches = []
+            if len(parts) > 3 and parts[3].strip():
+                branches_raw = parts[3].strip()
+                branches_raw = branches_raw.strip("()")
+                if branches_raw:
+                    for b in branches_raw.replace("HEAD -> ", "").split(","):
+                        b = b.strip()
+                        if b and not b.startswith("tag:"):
+                            branches.append(b)
+
+            commits.append(
+                {
+                    "hash": hash7,
+                    "message": message,
+                    "branches": branches,
+                    "graph_line": graph_line,
+                }
+            )
+
+    return commits