gitquest 0.1.0__py3-none-any.whl

gitquest/__init__.py

@@ -0,0 +1,9 @@
+"""gitquest - Turn your git commit history into a playable ASCII dungeon roguelike.
+
+Same repo + same seed = same dungeon. Explore rooms generated from real
+commits, fight keyword-spawned monsters, gain language XP, and finish with a
+shareable career flex card.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

gitquest/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m gitquest`` to launch the game."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

gitquest/cli.py

@@ -0,0 +1,149 @@
+"""Command-line entry point and argument parsing for gitquest.
+
+Step 1 (scaffold): wires up argument parsing and prints a placeholder banner so
+``gitquest`` and ``python -m gitquest`` both work. Later build steps replace the
+placeholder with the real game loop.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+
+BANNER = r"""
+   ____ _ _    ___                  _
+  / ___(_) |_ / _ \ _   _  ___  ___| |_
+ | |  _| | __| | | | | | |/ _ \/ __| __|
+ | |_| | | |_| |_| | |_| |  __/\__ \ |_
+  \____|_|\__|\__\_\\__,_|\___||___/\__|
+
+      Your commits. Your dungeon. Your legend.
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser for the ``gitquest`` command."""
+    parser = argparse.ArgumentParser(
+        prog="gitquest",
+        description="Turn your git commit history into a playable ASCII dungeon roguelike.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  gitquest                 play on the current repo\n"
+            "  gitquest --path ../repo  play on another repo\n"
+            "  gitquest --seed 42       force a specific dungeon seed\n"
+            "  gitquest --stats-only    skip the dungeon, just show the flex card\n"
+        ),
+    )
+    parser.add_argument(
+        "--path",
+        default=".",
+        metavar="REPO",
+        help="path to the git repository to play (default: current directory)",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=None,
+        metavar="N",
+        help="override the procedural-generation seed (default: derived from repo)",
+    )
+    parser.add_argument(
+        "--fast",
+        action="store_true",
+        help="skip animations and typewriter effects",
+    )
+    parser.add_argument(
+        "--stats-only",
+        action="store_true",
+        help="skip gameplay and print only the final flex card",
+    )
+    parser.add_argument(
+        "--max-commits",
+        type=int,
+        default=300,
+        metavar="N",
+        help="cap/sample commits for very large repos (default: 300)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"gitquest {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point. Parses args and runs gitquest.
+
+    Returns a process exit code.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # Imports are local so ``--help``/``--version`` stay fast and dependency-light.
+    import random
+
+    from rich.console import Console
+    from rich.text import Text
+
+    from .engine import GameEngine
+    from .entities import Player
+    from .flexcard import render_flexcard
+    from .generator import generate_dungeon
+    from .git_parser import (
+        EmptyHistoryError,
+        NotAGitRepoError,
+        parse_repo,
+    )
+    from .renderer import Renderer
+
+    console = Console()
+
+    # --- Parse the repository --------------------------------------------- #
+    try:
+        repo = parse_repo(args.path, max_commits=args.max_commits)
+    except NotAGitRepoError:
+        console.print(
+            f"[bold red]✗ {os.path.abspath(args.path)} is not a git repository.[/bold red]\n"
+            "[grey62]Run gitquest from inside a repo, or pass --path <repo>.[/grey62]"
+        )
+        return 2
+    except EmptyHistoryError:
+        console.print(
+            "[bold red]✗ This repository has no commits yet.[/bold red]\n"
+            "[grey62]Make a commit and try again — every legend starts somewhere.[/grey62]"
+        )
+        return 2
+    except Exception as exc:  # pragma: no cover - defensive
+        console.print(f"[bold red]✗ Failed to read repository:[/bold red] {exc}")
+        return 1
+
+    # --- Generate the dungeon --------------------------------------------- #
+    dungeon = generate_dungeon(repo, user_seed=args.seed)
+    player = Player(name=repo.head.author_name or "Hero")
+
+    # --- Stats-only: silent auto run, then just the flex card ------------- #
+    if args.stats_only:
+        engine = GameEngine(dungeon, player, interactive=False)
+        engine.run()
+        render_flexcard(player, dungeon, engine.victorious, console=console)
+        return 0
+
+    # --- Full interactive play -------------------------------------------- #
+    console.print(Text(BANNER, style="bold green"))
+    renderer = Renderer(console=console, fast=args.fast)
+    rng = random.Random(dungeon.seed ^ 0x5EED)
+    engine = GameEngine(dungeon, player, renderer=renderer, rng=rng, interactive=True)
+    engine.run()
+
+    render_flexcard(player, dungeon, engine.victorious, console=console)
+    return 0
+
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gitquest/combat.py

@@ -0,0 +1,91 @@
+"""Lightweight, deterministic-by-rng combat math.
+
+All functions take an explicit :class:`random.Random` so combat is fully
+reproducible in tests (and during automated/demo playthroughs). The engine owns
+the turn loop and player input; this module only resolves the numbers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from random import Random
+
+from .entities import Item, Monster, Player
+
+CRIT_CHANCE = 0.12
+CRIT_MULTIPLIER = 1.8
+DAMAGE_VARIANCE = 0.20
+DEFEND_REDUCTION = 0.5  # fraction of incoming damage blocked while defending
+
+
+@dataclass
+class AttackResult:
+    """Outcome of a single attack."""
+
+    damage: int
+    crit: bool
+    target_defeated: bool
+
+
+def compute_damage(
+    attack: int,
+    defense: int,
+    rng: Random,
+    *,
+    defending: bool = False,
+) -> tuple[int, bool]:
+    """Return ``(damage, is_crit)`` for an attack against a defense value.
+
+    Damage is ``attack`` mitigated by half the target's defense, jittered for
+    variety, with a chance to crit. Always at least 1 so fights end.
+    """
+    base = max(1.0, attack - defense * 0.5)
+    jitter = rng.uniform(1.0 - DAMAGE_VARIANCE, 1.0 + DAMAGE_VARIANCE)
+    crit = rng.random() < CRIT_CHANCE
+    dmg = base * jitter
+    if crit:
+        dmg *= CRIT_MULTIPLIER
+    if defending:
+        dmg *= 1.0 - DEFEND_REDUCTION
+    return max(1, int(round(dmg))), crit
+
+
+def player_attacks(player: Player, monster: Monster, rng: Random) -> AttackResult:
+    """Resolve the player's attack on a monster, mutating monster HP."""
+    dmg, crit = compute_damage(player.attack, monster.defense, rng)
+    monster.hp = max(0, monster.hp - dmg)
+    player.damage_dealt += dmg
+    return AttackResult(damage=dmg, crit=crit, target_defeated=not monster.is_alive)
+
+
+def monster_attacks(
+    monster: Monster,
+    player: Player,
+    rng: Random,
+    *,
+    player_defending: bool = False,
+) -> AttackResult:
+    """Resolve a monster's attack on the player, mutating player HP."""
+    dmg, crit = compute_damage(
+        monster.attack, player.defense, rng, defending=player_defending
+    )
+    player.hp = max(0, player.hp - dmg)
+    player.damage_taken += dmg
+    return AttackResult(damage=dmg, crit=crit, target_defeated=not player.is_alive)
+
+
+def use_potion(player: Player, potion: Item) -> int:
+    """Consume a potion, healing the player. Returns HP actually restored."""
+    if potion not in player.inventory:
+        return 0
+    before = player.hp
+    player.hp = min(player.max_hp, player.hp + potion.value)
+    player.inventory.remove(potion)
+    player.potions_used += 1
+    return player.hp - before
+
+
+def choose_monster_target(monster: Monster, rng: Random) -> str:
+    """Flavor helper: pick how a monster telegraphs its attack."""
+    verbs = ["lunges", "swipes", "hurls a stack trace", "casts a regex", "bites"]
+    return rng.choice(verbs)

gitquest/data/items.json

@@ -0,0 +1,38 @@
+{
+  "potion": [
+    "Vial of Hotfix",
+    "Caffeine Elixir",
+    "Rubber Duck Tonic",
+    "Stack Trace Salve",
+    "Green Build Brew"
+  ],
+  "weapon": [
+    "Refactoring Blade",
+    "Debugger Dagger",
+    "Linter Lance",
+    "Git Blame Bow",
+    "Commandline Cutlass",
+    "Regex Rapier"
+  ],
+  "armor": [
+    "Test Coverage Cloak",
+    "Type-Hint Hauberk",
+    "CI Shield",
+    "Mutex Mail",
+    "Exception Handler Helm"
+  ],
+  "relic": [
+    "Idol of Clean Code",
+    "Ancient Changelog",
+    "Tome of Documentation",
+    "Sacred .gitignore",
+    "Charm of Code Review"
+  ],
+  "treasure": [
+    "Pouch of Story Points",
+    "Bag of Bounty Bug Rewards",
+    "Cache of Merge Credits",
+    "Sprint Velocity Coins",
+    "Open Source Stars"
+  ]
+}

gitquest/data/monsters.json

@@ -0,0 +1,106 @@
+{
+  "Bug": {
+    "keywords": ["fix", "bug", "hotfix", "patch", "issue", "error", "crash", "broke", "broken"],
+    "art": "(>_<)",
+    "names": [
+      "Null Pointer",
+      "Off-by-One",
+      "Race Condition",
+      "Segfault Spawn",
+      "Heisenbug",
+      "Memory Leak",
+      "Stack Overflow",
+      "Infinite Loop",
+      "Dangling Reference",
+      "Deadlock Drake"
+    ]
+  },
+  "Feature": {
+    "keywords": ["feat", "feature", "add", "implement", "introduce", "new", "create", "support"],
+    "art": "(o_O)",
+    "names": [
+      "Scope Creep",
+      "Spec Wraith",
+      "Requirement Hydra",
+      "Edge Case Imp",
+      "Backlog Beast",
+      "Feature Flag Fiend",
+      "MVP Marauder",
+      "Roadmap Reaver"
+    ]
+  },
+  "Refactor": {
+    "keywords": ["refactor", "cleanup", "clean", "rename", "restructure", "simplify", "tidy", "reorganize"],
+    "art": "(~_~)",
+    "names": [
+      "Refactor Wraith",
+      "Tech Debt Golem",
+      "Spaghetti Serpent",
+      "Legacy Lurker",
+      "Coupling Creeper",
+      "God Object",
+      "Circular Dependency"
+    ]
+  },
+  "Test": {
+    "keywords": ["test", "tests", "spec", "coverage", "ci", "pytest", "unit"],
+    "art": "(x_x)",
+    "names": [
+      "Flaky Test",
+      "Red Build",
+      "Mock Mimic",
+      "Assertion Apparition",
+      "Coverage Gap",
+      "Timeout Terror"
+    ]
+  },
+  "Docs": {
+    "keywords": ["docs", "doc", "documentation", "readme", "comment", "typo", "spelling"],
+    "art": "(._.)",
+    "names": [
+      "Doc Golem",
+      "Typo Sprite",
+      "Lorem Ipsum Lich",
+      "Stale Comment",
+      "Markdown Mummy",
+      "TODO Phantom"
+    ]
+  },
+  "Build": {
+    "keywords": ["build", "deps", "dependency", "bump", "release", "version", "config", "chore", "deploy", "docker"],
+    "art": "(O_O)",
+    "names": [
+      "Dependency Demon",
+      "Version Conflict",
+      "Broken Pipeline",
+      "Config Cultist",
+      "Yaml Yeti",
+      "Docker Daemon"
+    ]
+  },
+  "Imp": {
+    "keywords": [],
+    "art": "(o_o)",
+    "names": [
+      "Commit Imp",
+      "Diff Goblin",
+      "Whitespace Wisp",
+      "Merge Gremlin",
+      "Branch Bandit",
+      "Stash Sprite",
+      "Rebase Wraith"
+    ]
+  },
+  "Boss": {
+    "keywords": ["merge"],
+    "art": "(\u00ac_\u00ac)",
+    "names": [
+      "The Merge Conflict",
+      "Octopus Merge Overlord",
+      "Diverged HEAD",
+      "The Rebase Tyrant",
+      "Force-Push Phantom",
+      "Detached HEAD Hydra"
+    ]
+  }
+}

gitquest/data/ranks.json

@@ -0,0 +1,14 @@
+{
+  "ranks": [
+    { "title": "Script Kiddie",       "min_score": 0 },
+    { "title": "Code Squire",         "min_score": 150 },
+    { "title": "Commit Knight",       "min_score": 400 },
+    { "title": "Merge Marauder",      "min_score": 800 },
+    { "title": "Refactor Ranger",     "min_score": 1400 },
+    { "title": "Senior Crusader",     "min_score": 2200 },
+    { "title": "Staff Sorcerer",      "min_score": 3200 },
+    { "title": "Principal Paladin",   "min_score": 4500 },
+    { "title": "Architect Archmage",  "min_score": 6500 },
+    { "title": "10x Demigod",         "min_score": 9000 }
+  ]
+}

gitquest/engine.py

@@ -0,0 +1,217 @@
+"""Game loop and state orchestration.
+
+The engine walks the player through the dungeon room by room (oldest commit ->
+HEAD), running combat, distributing loot, and handling progression. It supports
+two modes:
+
+* **interactive** – renders via :class:`~gitquest.renderer.Renderer` and prompts
+  the player for combat actions.
+* **auto** – resolves everything silently and deterministically (driven by the
+  seeded RNG). Used by ``--stats-only`` and by tests to simulate a full run.
+"""
+
+from __future__ import annotations
+
+import random
+
+from . import combat
+from .entities import Dungeon, Item, ItemKind, Player, Room
+from .renderer import Renderer
+
+# Player retreats from a fight only this often (keeps runs honest).
+RUN_SUCCESS_CHANCE = 0.5
+# Auto-play drinks a potion when HP drops below this fraction of max.
+AUTO_POTION_THRESHOLD = 0.4
+
+
+class GameEngine:
+    """Drives a single playthrough of a generated dungeon."""
+
+    def __init__(
+        self,
+        dungeon: Dungeon,
+        player: Player,
+        renderer: Renderer | None = None,
+        rng: random.Random | None = None,
+        *,
+        interactive: bool = True,
+    ) -> None:
+        self.dungeon = dungeon
+        self.player = player
+        self.renderer = renderer
+        self.interactive = interactive
+        # Combat RNG is seeded from the dungeon so auto runs are reproducible.
+        self.rng = rng or random.Random(dungeon.seed ^ 0x5EED)
+
+    # -- public API -------------------------------------------------------- #
+
+    def run(self) -> Player:
+        """Play through every room. Returns the (mutated) player."""
+        if self.interactive and self.renderer:
+            self.renderer.intro(self.dungeon, self.player)
+            self.renderer.pause("Press [bold]Enter[/bold] to enter the dungeon")
+
+        for room in self.dungeon.rooms:
+            self._enter_room(room)
+            if not self.player.is_alive:
+                if self.interactive and self.renderer:
+                    self.renderer.player_died(self.player, room)
+                break
+
+        return self.player
+
+    @property
+    def victorious(self) -> bool:
+        return self.player.is_alive
+
+    # -- room flow --------------------------------------------------------- #
+
+    def _enter_room(self, room: Room) -> None:
+        if self.interactive and self.renderer:
+            self.renderer.room_header(room, room.index, self.dungeon.size)
+
+        # Languages coded in this commit fill the skill tree.
+        self.player.grant_language_xp(room.languages)
+        if self.interactive and self.renderer:
+            self.renderer.language_gain(room.languages)
+
+        # Fight everything that lives here.
+        for monster in room.monsters:
+            if not monster.is_alive:
+                continue
+            if self.interactive and self.renderer:
+                self.renderer.encounter(monster)
+            self._fight(monster)
+            if not self.player.is_alive:
+                return
+
+        # Loot + room-clear reward.
+        self._collect_loot(room)
+        clear_bonus = 5 + room.index
+        levels = self.player.add_xp(clear_bonus)
+        self.player.rooms_cleared += 1
+        if self.interactive and self.renderer:
+            if levels:
+                self.renderer.level_up(self.player, levels)
+            self.renderer.room_cleared(room)
+            self.renderer.pause()
+
+    # -- combat ------------------------------------------------------------ #
+
+    def _fight(self, monster) -> None:
+        """Run a turn-based duel until the monster or player falls (or flees)."""
+        while monster.is_alive and self.player.is_alive:
+            action = self._choose_action(monster)
+
+            if action == "run":
+                if self.rng.random() < RUN_SUCCESS_CHANCE:
+                    if self.interactive and self.renderer:
+                        self.renderer.run_line(True)
+                    return
+                if self.interactive and self.renderer:
+                    self.renderer.run_line(False)
+                self._monster_turn(monster, player_defending=False)
+                continue
+
+            defending = action == "defend"
+
+            if action == "item":
+                used = self._use_potion()
+                if not used:
+                    # Cancelled / no potion -> turn not spent; re-prompt.
+                    if not self.interactive:
+                        defending = False  # fall through to attack in auto mode
+                    else:
+                        continue
+
+            if action == "attack":
+                result = combat.player_attacks(self.player, monster, self.rng)
+                if self.interactive and self.renderer:
+                    self.renderer.attack_line(
+                        self.player.name, monster.name, result.damage, result.crit, "green"
+                    )
+                if result.target_defeated:
+                    self._reward_kill(monster)
+                    return
+            elif action == "defend" and self.interactive and self.renderer:
+                self.renderer.defend_line(self.player)
+
+            # Monster retaliates.
+            self._monster_turn(monster, player_defending=defending)
+
+        if self.interactive and self.renderer:
+            self.renderer.combat_status(self.player, monster)
+
+    def _monster_turn(self, monster, *, player_defending: bool) -> None:
+        if not monster.is_alive:
+            return
+        result = combat.monster_attacks(
+            monster, self.player, self.rng, player_defending=player_defending
+        )
+        if self.interactive and self.renderer:
+            color = "bright_red" if monster.is_boss else "red"
+            self.renderer.attack_line(
+                monster.name, self.player.name, result.damage, result.crit, color
+            )
+
+    def _choose_action(self, monster) -> str:
+        if self.interactive and self.renderer:
+            return self.renderer.prompt_action(self.player)
+        # Auto strategy: heal when low and potions exist, else attack.
+        if (
+            self.player.potions
+            and self.player.hp < self.player.max_hp * AUTO_POTION_THRESHOLD
+        ):
+            return "item"
+        return "attack"
+
+    def _use_potion(self) -> bool:
+        if self.interactive and self.renderer:
+            potion = self.renderer.choose_potion(self.player)
+        else:
+            potions = self.player.potions
+            potion = potions[0] if potions else None
+        if potion is None:
+            return False
+        healed = combat.use_potion(self.player, potion)
+        if self.interactive and self.renderer:
+            self.renderer.heal_line(self.player, potion, healed)
+        return True
+
+    def _reward_kill(self, monster) -> None:
+        self.player.gold += monster.gold_reward
+        levels = self.player.add_xp(monster.xp_reward)
+        self.player.kills += 1
+        if monster.is_boss:
+            self.player.bosses_slain += 1
+        if self.interactive and self.renderer:
+            self.renderer.monster_defeated(monster, monster.xp_reward, monster.gold_reward)
+            if levels:
+                self.renderer.level_up(self.player, levels)
+
+    # -- loot -------------------------------------------------------------- #
+
+    def _collect_loot(self, room: Room) -> None:
+        if not room.items:
+            if self.interactive and self.renderer:
+                self.renderer.no_loot()
+            return
+        for item in room.items:
+            self._apply_item(item)
+            self.player.items_collected += 1
+            if self.interactive and self.renderer:
+                self.renderer.loot(item)
+
+    def _apply_item(self, item: Item) -> None:
+        """Permanently apply non-potion loot; stash potions for combat use."""
+        if item.kind == ItemKind.POTION:
+            self.player.inventory.append(item)
+        elif item.kind == ItemKind.WEAPON:
+            self.player.attack += item.value
+        elif item.kind == ItemKind.ARMOR:
+            self.player.defense += item.value
+        elif item.kind == ItemKind.RELIC:
+            self.player.max_hp += item.value
+            self.player.hp += item.value
+        elif item.kind == ItemKind.TREASURE:
+            self.player.gold += item.value