gitquest 0.1.0__py3-none-any.whl

gitquest/git_parser.py

@@ -0,0 +1,409 @@
+"""Extract and normalize git commit history into plain dataclasses.
+
+This module is the single source of truth for *reading* a repository. It tries
+:mod:`git` (GitPython) first and transparently falls back to shelling out to the
+``git`` binary, so gitquest works even where GitPython is unavailable.
+
+The output is a :class:`RepoData` object containing commits ordered oldest ->
+newest (the direction the player travels: from the repo's birth toward HEAD).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+# --------------------------------------------------------------------------- #
+# Errors
+# --------------------------------------------------------------------------- #
+
+
+class NotAGitRepoError(Exception):
+    """Raised when the target path is not inside a git repository."""
+
+
+class EmptyHistoryError(Exception):
+    """Raised when a repository has no commits to play through."""
+
+
+# --------------------------------------------------------------------------- #
+# Language detection
+# --------------------------------------------------------------------------- #
+
+# Map of lower-cased file extension -> human language/skill name.
+EXTENSION_LANGUAGE: dict[str, str] = {
+    ".py": "Python",
+    ".pyi": "Python",
+    ".ipynb": "Python",
+    ".js": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".jsx": "JavaScript",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".rs": "Rust",
+    ".go": "Go",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".kts": "Kotlin",
+    ".c": "C",
+    ".h": "C",
+    ".cpp": "C++",
+    ".cc": "C++",
+    ".cxx": "C++",
+    ".hpp": "C++",
+    ".cs": "C#",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".swift": "Swift",
+    ".scala": "Scala",
+    ".sh": "Shell",
+    ".bash": "Shell",
+    ".zsh": "Shell",
+    ".ps1": "PowerShell",
+    ".lua": "Lua",
+    ".r": "R",
+    ".dart": "Dart",
+    ".ex": "Elixir",
+    ".exs": "Elixir",
+    ".clj": "Clojure",
+    ".hs": "Haskell",
+    ".ml": "OCaml",
+    ".sql": "SQL",
+    ".html": "HTML",
+    ".htm": "HTML",
+    ".css": "CSS",
+    ".scss": "CSS",
+    ".sass": "CSS",
+    ".less": "CSS",
+    ".vue": "Vue",
+    ".svelte": "Svelte",
+    ".md": "Docs",
+    ".rst": "Docs",
+    ".txt": "Docs",
+    ".json": "Config",
+    ".yaml": "Config",
+    ".yml": "Config",
+    ".toml": "Config",
+    ".ini": "Config",
+    ".cfg": "Config",
+    ".xml": "Config",
+}
+
+
+def language_for_file(filename: str) -> str:
+    """Return the language/skill name for a filename based on its extension."""
+    ext = Path(filename).suffix.lower()
+    return EXTENSION_LANGUAGE.get(ext, "Misc")
+
+
+# --------------------------------------------------------------------------- #
+# Data model
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class CommitInfo:
+    """Normalized representation of a single commit."""
+
+    sha: str
+    short_sha: str
+    author_name: str
+    author_email: str
+    timestamp: datetime
+    summary: str          # first line of the commit message
+    message: str          # full commit message
+    insertions: int
+    deletions: int
+    files: list[str] = field(default_factory=list)
+    is_merge: bool = False
+    parent_count: int = 1
+
+    @property
+    def files_changed(self) -> int:
+        return len(self.files)
+
+    @property
+    def churn(self) -> int:
+        """Total lines touched (added + removed)."""
+        return self.insertions + self.deletions
+
+    @property
+    def languages(self) -> dict[str, int]:
+        """Count of touched files per language for this commit."""
+        counts: dict[str, int] = {}
+        for f in self.files:
+            lang = language_for_file(f)
+            counts[lang] = counts.get(lang, 0) + 1
+        return counts
+
+
+@dataclass
+class RepoData:
+    """Everything gitquest needs to know about a repository."""
+
+    name: str
+    path: str
+    commits: list[CommitInfo]  # oldest -> newest
+    sampled: bool = False
+    total_commits: int = 0
+
+    @property
+    def head(self) -> CommitInfo:
+        return self.commits[-1]
+
+    @property
+    def first(self) -> CommitInfo:
+        return self.commits[0]
+
+    @property
+    def authors(self) -> list[str]:
+        seen: dict[str, None] = {}
+        for c in self.commits:
+            seen.setdefault(c.author_name, None)
+        return list(seen)
+
+    @property
+    def total_insertions(self) -> int:
+        return sum(c.insertions for c in self.commits)
+
+    @property
+    def total_deletions(self) -> int:
+        return sum(c.deletions for c in self.commits)
+
+    @property
+    def merge_count(self) -> int:
+        return sum(1 for c in self.commits if c.is_merge)
+
+    @property
+    def language_totals(self) -> dict[str, int]:
+        totals: dict[str, int] = {}
+        for c in self.commits:
+            for lang, n in c.languages.items():
+                totals[lang] = totals.get(lang, 0) + n
+        return dict(sorted(totals.items(), key=lambda kv: kv[1], reverse=True))
+
+
+# --------------------------------------------------------------------------- #
+# Sampling
+# --------------------------------------------------------------------------- #
+
+
+def _sample_evenly(items: list, max_items: int) -> list:
+    """Deterministically down-sample a list while keeping first and last.
+
+    Picks evenly-spaced indices so the dungeon still spans the whole repo
+    history. Stable for a given (len, max_items) pair -> reproducible.
+    """
+    n = len(items)
+    if n <= max_items:
+        return items
+    # Always keep endpoints; evenly space the rest.
+    step = (n - 1) / (max_items - 1)
+    indices = sorted({round(i * step) for i in range(max_items)})
+    return [items[i] for i in indices]
+
+
+# --------------------------------------------------------------------------- #
+# GitPython backend
+# --------------------------------------------------------------------------- #
+
+
+def _parse_with_gitpython(path: str, max_commits: int) -> RepoData | None:
+    """Parse using GitPython. Returns None if GitPython is unavailable."""
+    try:
+        import git  # type: ignore
+    except ImportError:
+        return None
+
+    try:
+        repo = git.Repo(path, search_parent_directories=True)
+    except git.exc.InvalidGitRepositoryError as exc:  # type: ignore[attr-defined]
+        raise NotAGitRepoError(f"{path} is not a git repository") from exc
+    except git.exc.NoSuchPathError as exc:  # type: ignore[attr-defined]
+        raise NotAGitRepoError(f"{path} does not exist") from exc
+
+    try:
+        raw = list(repo.iter_commits())  # newest -> oldest
+    except Exception as exc:  # bare repo / no HEAD / empty
+        raise EmptyHistoryError("repository has no commits") from exc
+
+    if not raw:
+        raise EmptyHistoryError("repository has no commits")
+
+    raw.reverse()  # oldest -> newest
+    total = len(raw)
+    sampled_raw = _sample_evenly(raw, max_commits)
+
+    commits: list[CommitInfo] = []
+    for c in sampled_raw:
+        stats = c.stats
+        files = list(stats.files.keys())
+        commits.append(
+            CommitInfo(
+                sha=c.hexsha,
+                short_sha=c.hexsha[:7],
+                author_name=str(c.author.name or "Unknown"),
+                author_email=str(c.author.email or ""),
+                timestamp=datetime.fromtimestamp(c.committed_date, tz=timezone.utc),
+                summary=c.summary or "",
+                message=c.message or "",
+                insertions=int(stats.total.get("insertions", 0)),
+                deletions=int(stats.total.get("deletions", 0)),
+                files=files,
+                is_merge=len(c.parents) > 1,
+                parent_count=len(c.parents),
+            )
+        )
+
+    name = _repo_name(repo.working_dir or path)
+    return RepoData(
+        name=name,
+        path=os.path.abspath(repo.working_dir or path),
+        commits=commits,
+        sampled=total > max_commits,
+        total_commits=total,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# git CLI fallback backend
+# --------------------------------------------------------------------------- #
+
+_RECORD_SEP = "\x1e"   # between commits
+_FIELD_SEP = "\x1f"    # between header fields
+
+
+def _run_git(path: str, args: list[str]) -> str:
+    result = subprocess.run(
+        ["git", "-C", path, *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        stderr = result.stderr.lower()
+        if "not a git repository" in stderr:
+            raise NotAGitRepoError(f"{path} is not a git repository")
+        raise RuntimeError(result.stderr.strip() or "git command failed")
+    return result.stdout
+
+
+def _parse_with_cli(path: str, max_commits: int) -> RepoData:
+    """Parse history by shelling out to ``git log --numstat``."""
+    # Verify it is a repo first (clear error if git is missing entirely).
+    try:
+        _run_git(path, ["rev-parse", "--is-inside-work-tree"])
+    except FileNotFoundError as exc:
+        raise RuntimeError("git executable not found on PATH") from exc
+
+    fmt = _FIELD_SEP.join(["%H", "%an", "%ae", "%ct", "%P", "%s", "%b"])
+    log_format = f"{_RECORD_SEP}{fmt}"
+    out = _run_git(
+        path,
+        ["log", "--numstat", "--no-color", f"--pretty=format:{log_format}"],
+    )
+
+    records = [r for r in out.split(_RECORD_SEP) if r.strip()]
+    if not records:
+        raise EmptyHistoryError("repository has no commits")
+
+    commits: list[CommitInfo] = []
+    for rec in records:
+        header, _, body = rec.partition("\n")
+        parts = header.split(_FIELD_SEP)
+        if len(parts) < 7:
+            continue
+        sha, an, ae, ct, parents, summary, msg_body = parts[:7]
+
+        insertions = deletions = 0
+        files: list[str] = []
+        for line in body.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            cols = line.split("\t")
+            if len(cols) != 3:
+                continue
+            add, rem, fname = cols
+            insertions += 0 if add == "-" else int(add)
+            deletions += 0 if rem == "-" else int(rem)
+            files.append(fname)
+
+        full_message = summary if not msg_body.strip() else f"{summary}\n{msg_body}"
+        commits.append(
+            CommitInfo(
+                sha=sha,
+                short_sha=sha[:7],
+                author_name=an or "Unknown",
+                author_email=ae or "",
+                timestamp=datetime.fromtimestamp(int(ct), tz=timezone.utc),
+                summary=summary,
+                message=full_message,
+                insertions=insertions,
+                deletions=deletions,
+                files=files,
+                is_merge=len(parents.split()) > 1,
+                parent_count=len(parents.split()),
+            )
+        )
+
+    commits.reverse()  # git log is newest-first -> make oldest-first
+    total = len(commits)
+    commits = _sample_evenly(commits, max_commits)
+
+    return RepoData(
+        name=_repo_name(path),
+        path=os.path.abspath(path),
+        commits=commits,
+        sampled=total > max_commits,
+        total_commits=total,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Public API
+# --------------------------------------------------------------------------- #
+
+
+def _repo_name(working_dir: str) -> str:
+    return os.path.basename(os.path.abspath(working_dir).rstrip(os.sep)) or "repo"
+
+
+def parse_repo(path: str = ".", max_commits: int = 300) -> RepoData:
+    """Parse a repository into normalized :class:`RepoData`.
+
+    Args:
+        path: Path inside the target git repository.
+        max_commits: Upper bound on commits; larger histories are evenly
+            down-sampled so generation stays fast and deterministic.
+
+    Raises:
+        NotAGitRepoError: The path is not within a git repository.
+        EmptyHistoryError: The repository contains no commits.
+    """
+    if not os.path.exists(path):
+        raise NotAGitRepoError(f"{path} does not exist")
+
+    data = _parse_with_gitpython(path, max_commits)
+    if data is None:
+        data = _parse_with_cli(path, max_commits)
+    return data
+
+
+if __name__ == "__main__":  # pragma: no cover - manual smoke test
+    import sys
+
+    repo = parse_repo(sys.argv[1] if len(sys.argv) > 1 else ".")
+    print(f"Repo: {repo.name}  ({len(repo.commits)} of {repo.total_commits} commits)")
+    print(f"Authors: {', '.join(repo.authors)}")
+    print(f"Languages: {repo.language_totals}")
+    print("First 5 rooms:")
+    for c in repo.commits[:5]:
+        tag = "MERGE" if c.is_merge else "     "
+        print(f"  [{tag}] {c.short_sha} +{c.insertions}/-{c.deletions} "
+              f"{c.files_changed}f  {c.summary[:50]}")

gitquest/renderer.py

@@ -0,0 +1,256 @@
+"""All terminal rendering for gitquest, built on `rich`.
+
+The engine talks to a :class:`Renderer` instead of calling ``print`` directly,
+which keeps game logic free of presentation concerns and makes it easy to run
+silent/auto playthroughs (the engine simply skips the renderer).
+"""
+
+from __future__ import annotations
+
+import time
+
+from rich.align import Align
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.prompt import Prompt
+from rich.table import Table
+from rich.text import Text
+
+from .entities import Dungeon, Item, Monster, Player
+
+KIND_COLOR = {
+    "Bug": "red",
+    "Feature": "magenta",
+    "Refactor": "yellow",
+    "Test": "cyan",
+    "Docs": "blue",
+    "Build": "green",
+    "Imp": "white",
+    "Boss": "bright_red",
+}
+
+
+def hp_bar(current: int, maximum: int, width: int = 24, color: str = "green") -> Text:
+    """Render a coloured HP bar as rich Text."""
+    maximum = max(1, maximum)
+    current = max(0, min(current, maximum))
+    filled = int(round(width * current / maximum))
+    bar = Text()
+    bar.append("█" * filled, style=color)
+    bar.append("░" * (width - filled), style="grey37")
+    bar.append(f" {current}/{maximum}", style="bold")
+    return bar
+
+
+class Renderer:
+    """Rich-powered presentation layer."""
+
+    def __init__(self, console: Console | None = None, fast: bool = False) -> None:
+        self.console = console or Console()
+        self.fast = fast
+
+    # -- timing helpers ---------------------------------------------------- #
+
+    def sleep(self, seconds: float) -> None:
+        if not self.fast:
+            time.sleep(seconds)
+
+    def pause(self, prompt: str = "Press [bold]Enter[/bold] to continue") -> None:
+        if self.fast:
+            return
+        self.console.print(f"[grey50]{prompt}…[/grey50]", end="")
+        try:
+            input()
+        except EOFError:
+            self.console.print()
+
+    def rule(self, text: str = "") -> None:
+        self.console.rule(text)
+
+    # -- intro / banners --------------------------------------------------- #
+
+    def banner(self, text: str) -> None:
+        self.console.print(Text(text, style="bold green"))
+
+    def intro(self, dungeon: Dungeon, player: Player) -> None:
+        body = Table.grid(padding=(0, 2))
+        body.add_column(style="bold cyan")
+        body.add_column()
+        body.add_row("Repository", dungeon.repo_name)
+        body.add_row("Seed", str(dungeon.seed))
+        body.add_row("Rooms (commits)", str(dungeon.size))
+        body.add_row("Merges (bosses)", str(dungeon.merge_count))
+        body.add_row("Allies (authors)", str(len(dungeon.authors)))
+        langs = ", ".join(list(dungeon.language_totals)[:5]) or "—"
+        body.add_row("Skill paths", langs)
+        if dungeon.sampled:
+            body.add_row(
+                "Note",
+                f"[yellow]Sampled {dungeon.size} of {dungeon.total_commits} commits[/yellow]",
+            )
+        self.console.print(
+            Panel(
+                body,
+                title="[bold]⚔️  GITQUEST  ⚔️[/bold]",
+                subtitle=f"hero: [bold]{player.name}[/bold]",
+                border_style="green",
+            )
+        )
+        self.console.print(
+            "[grey62]Travel from the repo's birth toward HEAD. "
+            "Clear every room. Become legend.[/grey62]\n"
+        )
+
+    # -- rooms ------------------------------------------------------------- #
+
+    def room_header(self, room, index: int, total: int) -> None:
+        kind = "💀 MINI-BOSS ROOM" if room.is_boss else f"Room {index + 1}/{total}"
+        border = "bright_red" if room.is_boss else "cyan"
+        info = Table.grid(padding=(0, 1))
+        info.add_row(f"[bold]{room.title}[/bold]")
+        info.add_row(
+            f"[grey62]{room.short_sha} · +{room.insertions}/-{room.deletions} · "
+            f"{room.flavor}[/grey62]"
+        )
+        if room.npc_name:
+            info.add_row(f"[blue]🧙 You meet {room.npc_name}, an ally from this commit.[/blue]")
+        self.console.print(Panel(info, title=kind, border_style=border, expand=True))
+
+    def language_gain(self, languages: dict[str, int]) -> None:
+        if not languages:
+            return
+        parts = [f"+{n} {lang}" for lang, n in languages.items()]
+        self.console.print(f"[green]🧠 Skill XP: {', '.join(parts)}[/green]")
+
+    # -- combat ------------------------------------------------------------ #
+
+    def encounter(self, monster: Monster) -> None:
+        color = KIND_COLOR.get(monster.kind, "white")
+        title = f"[{color}]A {monster.kind} appears![/{color}]"
+        art = Text(monster.art, style=f"bold {color}")
+        name = Text(monster.name, style=f"bold {color}")
+        stats = Text(
+            f"HP {monster.hp}  ·  ATK {monster.attack}  ·  DEF {monster.defense}",
+            style="grey70",
+        )
+        self.console.print(
+            Panel(
+                Align.center(Group(art, name, stats)),
+                title=title,
+                border_style=color,
+            )
+        )
+
+    def combat_status(self, player: Player, monster: Monster) -> None:
+        color = KIND_COLOR.get(monster.kind, "white")
+        grid = Table.grid(padding=(0, 2))
+        grid.add_column(justify="right", style="bold")
+        grid.add_column()
+        grid.add_row(player.name, hp_bar(player.hp, player.max_hp, color="green"))
+        grid.add_row(monster.name, hp_bar(monster.hp, monster.max_hp, color=color))
+        self.console.print(grid)
+
+    def prompt_action(self, player: Player) -> str:
+        choices = {"a": "attack", "d": "defend", "i": "item", "r": "run"}
+        n_potions = len(player.potions)
+        hint = (
+            f"[bold green]A[/bold green]ttack  "
+            f"[bold yellow]D[/bold yellow]efend  "
+            f"[bold cyan]I[/bold cyan]tem({n_potions})  "
+            f"[bold red]R[/bold red]un"
+        )
+        self.console.print(hint)
+        ans = Prompt.ask("Your move", choices=list(choices), default="a", show_choices=False)
+        return choices[ans]
+
+    def choose_potion(self, player: Player) -> Item | None:
+        potions = player.potions
+        if not potions:
+            self.console.print("[grey62]No potions to drink![/grey62]")
+            return None
+        table = Table(title="Potions", border_style="cyan")
+        table.add_column("#", justify="right")
+        table.add_column("Item")
+        table.add_column("Effect")
+        for i, p in enumerate(potions, 1):
+            table.add_row(str(i), f"{p.icon} {p.name}", p.description)
+        self.console.print(table)
+        idx = Prompt.ask(
+            "Drink which? (0 to cancel)",
+            choices=[str(i) for i in range(0, len(potions) + 1)],
+            default="1",
+        )
+        i = int(idx)
+        return potions[i - 1] if 1 <= i <= len(potions) else None
+
+    def attack_line(self, attacker: str, target: str, damage: int, crit: bool, color: str) -> None:
+        crit_tag = " [bold yellow]CRIT![/bold yellow]" if crit else ""
+        self.console.print(
+            f"[{color}]» {attacker}[/{color}] hits [bold]{target}[/bold] for "
+            f"[bold]{damage}[/bold] damage.{crit_tag}"
+        )
+        self.sleep(0.35)
+
+    def defend_line(self, player: Player) -> None:
+        self.console.print(f"[yellow]» {player.name} raises a guard.[/yellow]")
+        self.sleep(0.25)
+
+    def heal_line(self, player: Player, item: Item, healed: int) -> None:
+        self.console.print(
+            f"[green]» {player.name} drinks {item.icon} {item.name}, +{healed} HP.[/green]"
+        )
+        self.sleep(0.3)
+
+    def run_line(self, success: bool) -> None:
+        if success:
+            self.console.print("[yellow]» You slip away from the fight![/yellow]")
+        else:
+            self.console.print("[red]» You can't escape![/red]")
+        self.sleep(0.3)
+
+    def monster_defeated(self, monster: Monster, xp: int, gold: int) -> None:
+        self.console.print(
+            f"[bold green]✔ {monster.name} defeated![/bold green] "
+            f"[grey70](+{xp} XP, +{gold} gold)[/grey70]"
+        )
+        self.sleep(0.3)
+
+    # -- loot / progression ------------------------------------------------ #
+
+    def loot(self, item: Item) -> None:
+        self.console.print(
+            f"[bold yellow]🎁 Looted {item.icon} {item.name}[/bold yellow] "
+            f"[grey70]— {item.description}[/grey70]"
+        )
+
+    def no_loot(self) -> None:
+        self.console.print("[grey50]No loot in this room.[/grey50]")
+
+    def level_up(self, player: Player, levels: int) -> None:
+        self.console.print(
+            Panel(
+                f"[bold yellow]LEVEL UP![/bold yellow]  You are now level "
+                f"[bold]{player.level}[/bold]!\n"
+                f"Max HP {player.max_hp} · ATK {player.attack} · DEF {player.defense} "
+                f"(fully healed)",
+                border_style="yellow",
+            )
+        )
+        self.sleep(0.4)
+
+    def room_cleared(self, room) -> None:
+        self.console.print("[green]✓ Room cleared.[/green]\n")
+        self.sleep(0.2)
+
+    def info(self, text: str) -> None:
+        self.console.print(text)
+
+    def player_died(self, player: Player, room) -> None:
+        self.console.print(
+            Panel(
+                f"[bold red]☠  You fell in room {room.index + 1}: {room.title}[/bold red]\n"
+                f"[grey70]The dungeon claims another developer. Your legend ends here.[/grey70]",
+                title="GAME OVER",
+                border_style="red",
+            )
+        )