gitquest 0.1.0__py3-none-any.whl

gitquest/entities.py

@@ -0,0 +1,169 @@
+"""Core game dataclasses: Player, Monster, Item, Room, Dungeon.
+
+These are intentionally behaviour-light data containers. Generation lives in
+:mod:`gitquest.generator`, combat in :mod:`gitquest.combat`, and orchestration
+in :mod:`gitquest.engine`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ItemKind(str, Enum):
+    """What an item does when used/collected."""
+
+    POTION = "potion"      # restores HP
+    WEAPON = "weapon"      # boosts attack
+    ARMOR = "armor"        # boosts defense
+    RELIC = "relic"        # boosts max HP / misc
+    TREASURE = "treasure"  # pure gold/score
+
+
+@dataclass
+class Item:
+    """A piece of loot derived from a changed file."""
+
+    name: str
+    kind: ItemKind
+    value: int               # magnitude of the effect (HP, atk, def, gold)
+    source_file: str = ""
+    description: str = ""
+
+    @property
+    def icon(self) -> str:
+        return {
+            ItemKind.POTION: "🧪",
+            ItemKind.WEAPON: "⚔️",
+            ItemKind.ARMOR: "🛡️",
+            ItemKind.RELIC: "💍",
+            ItemKind.TREASURE: "💰",
+        }[self.kind]
+
+
+@dataclass
+class Monster:
+    """An enemy spawned from a commit's message keywords + churn."""
+
+    name: str
+    kind: str                # archetype, e.g. "Bug", "Feature", "Refactor"
+    hp: int
+    max_hp: int
+    attack: int
+    defense: int
+    xp_reward: int
+    gold_reward: int = 0
+    is_boss: bool = False
+    art: str = "(o_o)"
+
+    @property
+    def is_alive(self) -> bool:
+        return self.hp > 0
+
+
+@dataclass
+class Room:
+    """A single dungeon room generated from one commit."""
+
+    index: int               # 0-based position in the dungeon
+    sha: str
+    short_sha: str
+    title: str               # commit summary, trimmed
+    npc_name: str            # commit author -> NPC/ally
+    size: str                # "cramped" | "modest" | "large" | "cavernous"
+    is_boss: bool
+    monsters: list[Monster] = field(default_factory=list)
+    items: list[Item] = field(default_factory=list)
+    languages: dict[str, int] = field(default_factory=dict)
+    insertions: int = 0
+    deletions: int = 0
+    flavor: str = ""
+
+    @property
+    def cleared(self) -> bool:
+        return all(not m.is_alive for m in self.monsters)
+
+
+@dataclass
+class Player:
+    """The hero. Stats grow as the player clears rooms and gains XP."""
+
+    name: str
+    hp: int = 30
+    max_hp: int = 30
+    attack: int = 6
+    defense: int = 2
+    level: int = 1
+    xp: int = 0
+    xp_to_next: int = 20
+    gold: int = 0
+    skill_tree: dict[str, int] = field(default_factory=dict)
+    inventory: list[Item] = field(default_factory=list)
+    # career stats
+    kills: int = 0
+    bosses_slain: int = 0
+    rooms_cleared: int = 0
+    items_collected: int = 0
+    potions_used: int = 0
+    damage_dealt: int = 0
+    damage_taken: int = 0
+
+    @property
+    def is_alive(self) -> bool:
+        return self.hp > 0
+
+    def grant_language_xp(self, languages: dict[str, int]) -> None:
+        """Fill the skill tree based on languages coded in a room."""
+        for lang, n in languages.items():
+            self.skill_tree[lang] = self.skill_tree.get(lang, 0) + n
+
+    @property
+    def top_skill(self) -> str:
+        if not self.skill_tree:
+            return "Generalist"
+        return max(self.skill_tree.items(), key=lambda kv: kv[1])[0]
+
+    def add_xp(self, amount: int) -> int:
+        """Add XP and resolve level-ups. Returns the number of levels gained.
+
+        Each level raises max HP, attack and defense, fully heals the player,
+        and increases the XP required for the next level.
+        """
+        self.xp += max(0, amount)
+        levels = 0
+        while self.xp >= self.xp_to_next:
+            self.xp -= self.xp_to_next
+            self.level += 1
+            levels += 1
+            self.max_hp += 5
+            self.attack += 2
+            self.defense += 1
+            self.hp = self.max_hp  # ding! full heal on level-up
+            self.xp_to_next = int(self.xp_to_next * 1.4) + 5
+        return levels
+
+    @property
+    def potions(self) -> list["Item"]:
+        return [i for i in self.inventory if i.kind == ItemKind.POTION]
+
+
+@dataclass
+class Dungeon:
+    """The full generated world plus the metadata used for the flex card."""
+
+    repo_name: str
+    repo_path: str
+    seed: int
+    rooms: list[Room]
+    authors: list[str]
+    language_totals: dict[str, int]
+    total_insertions: int
+    total_deletions: int
+    total_commits: int
+    sampled: bool
+    merge_count: int
+
+    @property
+    def size(self) -> int:
+        return len(self.rooms)

gitquest/flexcard.py

@@ -0,0 +1,146 @@
+"""Final shareable "flex card": ranking + ASCII career summary.
+
+Designed to look good as a terminal screenshot for sharing. The career score is
+deterministic for a given playthrough, and the rank is looked up from
+``data/ranks.json``.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+
+from rich.align import Align
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .entities import Dungeon, Player
+
+
+@lru_cache(maxsize=1)
+def _ranks() -> list[dict]:
+    resource = resources.files("gitquest").joinpath("data", "ranks.json")
+    with resource.open("r", encoding="utf-8") as fh:
+        return json.load(fh)["ranks"]
+
+
+def career_score(player: Player, dungeon: Dungeon, victorious: bool) -> int:
+    """Compute a single headline score from the playthrough.
+
+    Rewards rooms cleared, kills, bosses, level, gold, and skill breadth, with a
+    completion bonus for reaching HEAD alive.
+    """
+    score = 0
+    score += player.rooms_cleared * 12
+    score += player.kills * 8
+    score += player.bosses_slain * 60
+    score += (player.level - 1) * 40
+    score += player.gold
+    score += player.items_collected * 5
+    score += sum(player.skill_tree.values()) * 3
+    score += len(player.skill_tree) * 15  # breadth bonus
+    if victorious:
+        score += 200 + dungeon.size * 5
+    return int(score)
+
+
+def rank_for_score(score: int) -> str:
+    """Return the highest rank title whose threshold the score meets."""
+    title = _ranks()[0]["title"]
+    for entry in _ranks():
+        if score >= entry["min_score"]:
+            title = entry["title"]
+        else:
+            break
+    return title
+
+
+def _bar(label: str, value: int, max_value: int, color: str, width: int = 18) -> Text:
+    max_value = max(1, max_value)
+    filled = int(round(width * min(value, max_value) / max_value))
+    t = Text()
+    t.append(f"{label:<12}", style="bold")
+    t.append("█" * filled, style=color)
+    t.append("░" * (width - filled), style="grey37")
+    t.append(f" {value}", style="bold")
+    return t
+
+
+def build_flexcard(
+    player: Player, dungeon: Dungeon, victorious: bool
+) -> Panel:
+    """Construct the rich Panel for the final flex card."""
+    score = career_score(player, dungeon, victorious)
+    rank = rank_for_score(score)
+
+    header = Text()
+    header.append("⚔  GITQUEST CAREER CARD  ⚔\n", style="bold green")
+    header.append(f"{dungeon.repo_name}", style="bold white")
+    header.append(f"   seed {dungeon.seed}\n", style="grey50")
+
+    rank_text = Text()
+    status = "VICTORIOUS" if victorious else "FELL IN BATTLE"
+    status_color = "bright_green" if victorious else "red"
+    rank_text.append(f"\n  RANK: ", style="bold")
+    rank_text.append(f"{rank}\n", style="bold yellow")
+    rank_text.append("  SCORE: ", style="bold")
+    rank_text.append(f"{score}\n", style="bold cyan")
+    rank_text.append("  STATUS: ", style="bold")
+    rank_text.append(f"{status}\n", style=f"bold {status_color}")
+
+    # Career stats table.
+    stats = Table.grid(padding=(0, 3))
+    stats.add_column(style="cyan", justify="right")
+    stats.add_column(style="bold")
+    stats.add_column(style="cyan", justify="right")
+    stats.add_column(style="bold")
+    stats.add_row("Level", str(player.level), "Gold", str(player.gold))
+    stats.add_row("HP", f"{player.hp}/{player.max_hp}", "Attack", str(player.attack))
+    stats.add_row("Defense", str(player.defense), "Rooms", str(player.rooms_cleared))
+    stats.add_row("Kills", str(player.kills), "Bosses", str(player.bosses_slain))
+    stats.add_row("Items", str(player.items_collected), "Potions used", str(player.potions_used))
+    stats.add_row("Dmg dealt", str(player.damage_dealt), "Dmg taken", str(player.damage_taken))
+
+    # Skill tree bars (top languages).
+    skill_rows: list[Text] = []
+    if player.skill_tree:
+        top = sorted(player.skill_tree.items(), key=lambda kv: kv[1], reverse=True)[:6]
+        max_skill = max(v for _, v in top)
+        palette = ["green", "cyan", "magenta", "yellow", "blue", "red"]
+        for i, (lang, val) in enumerate(top):
+            skill_rows.append(_bar(lang, val, max_skill, palette[i % len(palette)]))
+    skill_group = Group(
+        Text("\n  SKILL TREE", style="bold green"),
+        *[Align.left(r) for r in skill_rows],
+    ) if skill_rows else Text("")
+
+    top_skill = player.top_skill
+    footer = Text(
+        f"\n  Specialization: {top_skill}  ·  "
+        f"{len(player.skill_tree)} skill paths explored\n"
+        "  generated by gitquest 🗡️  ·  share your run!",
+        style="grey62",
+    )
+
+    body = Group(
+        Align.center(header),
+        rank_text,
+        Text("\n  CAREER STATS", style="bold green"),
+        stats,
+        skill_group,
+        footer,
+    )
+
+    border = "green" if victorious else "red"
+    return Panel(body, border_style=border, title="[bold]flex card[/bold]", padding=(1, 3))
+
+
+def render_flexcard(
+    player: Player, dungeon: Dungeon, victorious: bool, console: Console | None = None
+) -> None:
+    """Print the flex card to the console."""
+    console = console or Console()
+    console.print(build_flexcard(player, dungeon, victorious))

gitquest/generator.py

@@ -0,0 +1,295 @@
+"""Deterministic dungeon generation: commit history -> playable world.
+
+Generation is seeded from the repository (hash of the first commit's SHA) unless
+the player overrides ``--seed``. Given the same repo and seed, the produced
+:class:`~gitquest.entities.Dungeon` is byte-for-byte identical, which is what
+makes gitquest runs reproducible and shareable.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+from functools import lru_cache
+from importlib import resources
+
+from .entities import Dungeon, Item, ItemKind, Monster, Room
+from .git_parser import CommitInfo, RepoData
+
+# --------------------------------------------------------------------------- #
+# Data loading
+# --------------------------------------------------------------------------- #
+
+
+@lru_cache(maxsize=None)
+def _load_data(filename: str) -> dict:
+    """Load and cache a JSON file from the packaged ``data`` directory."""
+    resource = resources.files("gitquest").joinpath("data", filename)
+    with resource.open("r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+@lru_cache(maxsize=1)
+def _keyword_index() -> list[tuple[str, str]]:
+    """Return (keyword, archetype) pairs sorted longest-first for matching."""
+    monsters = _load_data("monsters.json")
+    pairs: list[tuple[str, str]] = []
+    for archetype, spec in monsters.items():
+        for kw in spec.get("keywords", []):
+            pairs.append((kw.lower(), archetype))
+    pairs.sort(key=lambda p: len(p[0]), reverse=True)
+    return pairs
+
+
+# --------------------------------------------------------------------------- #
+# Seed
+# --------------------------------------------------------------------------- #
+
+
+def compute_seed(repo: RepoData, user_seed: int | None = None) -> int:
+    """Derive the generation seed from the repo, or honor a user override."""
+    if user_seed is not None:
+        return int(user_seed)
+    digest = hashlib.sha256(repo.first.sha.encode("utf-8")).hexdigest()
+    return int(digest[:16], 16)
+
+
+# --------------------------------------------------------------------------- #
+# Classification helpers
+# --------------------------------------------------------------------------- #
+
+
+def classify_archetype(commit: CommitInfo) -> str:
+    """Map a commit's message keywords to a monster archetype.
+
+    Merge commits always produce a boss. Otherwise the first matching keyword
+    (longest first) wins; unmatched commits spawn generic Imps.
+    """
+    if commit.is_merge:
+        return "Boss"
+    text = f"{commit.summary} {commit.message}".lower()
+    for keyword, archetype in _keyword_index():
+        if keyword and keyword in text:
+            return archetype
+    return "Imp"
+
+
+def _room_size(churn: int) -> str:
+    if churn < 20:
+        return "cramped"
+    if churn < 100:
+        return "modest"
+    if churn < 400:
+        return "large"
+    return "cavernous"
+
+
+_SIZE_FLAVOR = {
+    "cramped": "a tight crawlspace of tangled diffs",
+    "modest": "a modest chamber lit by terminal glow",
+    "large": "a sprawling hall echoing with merge conflicts",
+    "cavernous": "a cavernous vault humming with churn",
+}
+
+
+# --------------------------------------------------------------------------- #
+# Monster + item factories
+# --------------------------------------------------------------------------- #
+
+
+def _make_monster(
+    rng: random.Random,
+    archetype: str,
+    churn: int,
+    depth: int,
+    depth_total: int,
+    is_boss: bool,
+) -> Monster:
+    spec = _load_data("monsters.json")[archetype]
+    name = rng.choice(spec["names"])
+    art = spec.get("art", "(o_o)")
+
+    capped = min(churn, 600)
+    depth_bonus = depth * 0.9
+    jitter = rng.uniform(0.85, 1.2)
+
+    hp = int((8 + capped / 10 + depth_bonus) * jitter) + 1
+    attack = int((3 + capped / 45 + depth * 0.30) * jitter) + 1
+    defense = int(capped / 150 + depth * 0.12)
+    xp_reward = int(9 + capped / 9 + depth * 1.6)
+    gold_reward = int(rng.randint(2, 8) + capped / 25 + depth * 0.5)
+
+    if is_boss:
+        hp = int(hp * 2.3) + 12
+        attack = int(attack * 1.4) + 2
+        defense = int(defense * 1.3) + 1
+        xp_reward = int(xp_reward * 3)
+        gold_reward = int(gold_reward * 3) + 10
+        name = f"{name} 👑"
+
+    return Monster(
+        name=name,
+        kind=archetype,
+        hp=hp,
+        max_hp=hp,
+        attack=attack,
+        defense=defense,
+        xp_reward=xp_reward,
+        gold_reward=gold_reward,
+        is_boss=is_boss,
+        art=art,
+    )
+
+
+# kind -> selection weight for normal loot rolls
+_ITEM_WEIGHTS: list[tuple[ItemKind, float]] = [
+    (ItemKind.POTION, 0.34),
+    (ItemKind.WEAPON, 0.20),
+    (ItemKind.ARMOR, 0.20),
+    (ItemKind.RELIC, 0.11),
+    (ItemKind.TREASURE, 0.15),
+]
+
+
+def _pick_item_kind(rng: random.Random) -> ItemKind:
+    roll = rng.random()
+    cumulative = 0.0
+    for kind, weight in _ITEM_WEIGHTS:
+        cumulative += weight
+        if roll <= cumulative:
+            return kind
+    return ItemKind.POTION
+
+
+def _make_item(
+    rng: random.Random,
+    kind: ItemKind,
+    churn: int,
+    depth: int,
+    source_file: str,
+) -> Item:
+    names = _load_data("items.json")[kind.value]
+    name = rng.choice(names)
+    base = min(churn, 400) / 20 + depth * 0.5
+
+    if kind == ItemKind.POTION:
+        value = int(8 + base) + rng.randint(0, 6)
+        desc = f"Restores {value} HP."
+    elif kind == ItemKind.WEAPON:
+        value = max(1, int(1 + base / 6)) + rng.randint(0, 2)
+        desc = f"+{value} attack."
+    elif kind == ItemKind.ARMOR:
+        value = max(1, int(base / 8)) + rng.randint(0, 2)
+        desc = f"+{value} defense."
+    elif kind == ItemKind.RELIC:
+        value = max(2, int(2 + base / 5))
+        desc = f"+{value} max HP."
+    else:  # TREASURE
+        value = int(5 + base * 2) + rng.randint(0, 10)
+        desc = f"Worth {value} gold."
+
+    return Item(name=name, kind=kind, value=value, source_file=source_file, description=desc)
+
+
+# --------------------------------------------------------------------------- #
+# Room + dungeon assembly
+# --------------------------------------------------------------------------- #
+
+
+def _build_room(
+    rng: random.Random,
+    commit: CommitInfo,
+    index: int,
+    depth_total: int,
+) -> Room:
+    churn = commit.churn
+    is_boss = commit.is_merge
+    archetype = classify_archetype(commit)
+    size = _room_size(churn)
+
+    # Monsters: one by default, a second guard in big non-boss rooms.
+    monsters: list[Monster] = []
+    if is_boss:
+        monsters.append(_make_monster(rng, "Boss", churn, index, depth_total, True))
+    else:
+        monsters.append(_make_monster(rng, archetype, churn, index, depth_total, False))
+        if churn >= 150 and rng.random() < 0.5:
+            monsters.append(
+                _make_monster(rng, archetype, churn // 2, index, depth_total, False)
+            )
+
+    # Loot from changed files (capped to keep inventory sane).
+    items: list[Item] = []
+    lootable = commit.files[:4]
+    for fname in lootable:
+        if rng.random() < 0.7:
+            kind = _pick_item_kind(rng)
+            items.append(_make_item(rng, kind, churn, index, fname))
+
+    title = (commit.summary or "(no message)").strip()
+    if len(title) > 60:
+        title = title[:57] + "..."
+
+    flavor = _SIZE_FLAVOR[size]
+
+    return Room(
+        index=index,
+        sha=commit.sha,
+        short_sha=commit.short_sha,
+        title=title,
+        npc_name=commit.author_name,
+        size=size,
+        is_boss=is_boss,
+        monsters=monsters,
+        items=items,
+        languages=commit.languages,
+        insertions=commit.insertions,
+        deletions=commit.deletions,
+        flavor=flavor,
+    )
+
+
+def generate_dungeon(repo: RepoData, user_seed: int | None = None) -> Dungeon:
+    """Build a deterministic :class:`Dungeon` from parsed repository data."""
+    seed = compute_seed(repo, user_seed)
+    rng = random.Random(seed)
+
+    depth_total = len(repo.commits)
+    rooms = [
+        _build_room(rng, commit, index, depth_total)
+        for index, commit in enumerate(repo.commits)
+    ]
+
+    return Dungeon(
+        repo_name=repo.name,
+        repo_path=repo.path,
+        seed=seed,
+        rooms=rooms,
+        authors=repo.authors,
+        language_totals=repo.language_totals,
+        total_insertions=repo.total_insertions,
+        total_deletions=repo.total_deletions,
+        total_commits=repo.total_commits,
+        sampled=repo.sampled,
+        merge_count=repo.merge_count,
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover - manual smoke test
+    import sys
+
+    from .git_parser import parse_repo
+
+    repo = parse_repo(sys.argv[1] if len(sys.argv) > 1 else ".")
+    seed_arg = int(sys.argv[2]) if len(sys.argv) > 2 else None
+    dungeon = generate_dungeon(repo, seed_arg)
+    print(f"Dungeon for {dungeon.repo_name}  seed={dungeon.seed}  rooms={dungeon.size}")
+    for room in dungeon.rooms:
+        kind = "BOSS" if room.is_boss else "room"
+        mob = room.monsters[0]
+        print(
+            f"  [{kind}] #{room.index:<3} {room.short_sha} {room.size:<9} "
+            f"{len(room.monsters)}m {len(room.items)}i | "
+            f"{mob.name} (hp{mob.hp}/atk{mob.attack}) <- {room.title[:34]}"
+        )