gitquest 0.1.0__tar.gz

gitquest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gitquest contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitquest-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: gitquest
+Version: 0.1.0
+Summary: Turn your git commit history into a playable ASCII dungeon roguelike.
+Author-email: jithin-jz <jithinjzx@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jithin-jz/gitquest
+Project-URL: Repository, https://github.com/jithin-jz/gitquest
+Project-URL: Issues, https://github.com/jithin-jz/gitquest/issues
+Keywords: git,game,roguelike,cli,ascii,terminal,rich
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Requires-Dist: GitPython>=3.1.30
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# gitquest 🗡️
+
+> **Your commits. Your dungeon. Your legend.**
+> Turn any git repository's history into a procedurally generated, playable
+> ASCII dungeon roguelike — right in your terminal.
+
+`gitquest` reads your repo's real commit history and deterministically builds a
+dungeon from it. Each commit becomes a room. Bug-fix commits spawn bugs. Merge
+commits become mini-bosses. The languages you've coded fill your skill tree.
+Clear every room from the repo's first commit to `HEAD`, then flex your career
+on a shareable stats card.
+
+**Same repo + same seed = the same dungeon, every time.** Reproducible and
+shareable.
+
+---
+
+## ✨ Demo
+
+<!--
+  📽️  ANIMATED GIF PLACEHOLDER
+  Drop a terminal recording here (e.g. via `asciinema` + `agg`, or a screen GIF).
+  Recommended: a ~20s clip of a fight + the final flex card.
+  ![gitquest demo](docs/demo.gif)
+-->
+
+```text
+   ____ _ _    ___                  _
+  / ___(_) |_ / _ \ _   _  ___  ___| |_
+ | |  _| | __| | | | | | |/ _ \/ __| __|
+ | |_| | | |_| |_| | |_| |  __/\__ \ |_
+  \____|_|\__|\__\_\\__,_|\___||___/\__|
+
+      Your commits. Your dungeon. Your legend.
+
+┌───────────────────────────────── Room 2/5 ──────────────────────────────────┐
+│ fix: bug in output handling                                                  │
+│ 33b27d3 · +2/-0 · a tight crawlspace of tangled diffs                        │
+│ 🧙 You meet Ada Lovelace, an ally from this commit.                          │
+└──────────────────────────────────────────────────────────────────────────────┘
+🧠 Skill XP: +1 Python, +1 JavaScript
+┌────────────────────────────── A Bug appears! ───────────────────────────────┐
+│                          (>_<)                                               │
+│                          Off-by-One                                          │
+│                          HP 11  ·  ATK 4  ·  DEF 0                           │
+└──────────────────────────────────────────────────────────────────────────────┘
+Attack  Defend  Item(0)  Run
+Your move (a): » Hero hits Off-by-One for 6 damage.
+✔ Off-by-One defeated! (+10 XP, +6 gold)
+```
+
+And the grand finale — the shareable **flex card**:
+
+```text
+┌───────────────────────────────── flex card ─────────────────────────────────┐
+│                    ⚔  GITQUEST CAREER CARD  ⚔                                │
+│                    my-repo   seed 17391773614721965407                       │
+│                                                                              │
+│     RANK: Senior Crusader                                                    │
+│     SCORE: 2310                                                              │
+│     STATUS: VICTORIOUS                                                        │
+│                                                                              │
+│     CAREER STATS                                                             │
+│       Level   11              Gold   642                                     │
+│       Kills   148           Bosses   12                                      │
+│     SKILL TREE                                                               │
+│   Python      ██████████████████ 220                                         │
+│   TypeScript  ███████████░░░░░░░ 130                                         │
+│     Specialization: Python  ·  6 skill paths explored                        │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Install
+
+The zero-friction way (isolated, recommended):
+
+```bash
+pipx install gitquest
+```
+
+Or with pip:
+
+```bash
+pip install gitquest
+```
+
+From source:
+
+```bash
+git clone https://github.com/jithin-jz/gitquest
+cd gitquest
+pip install .
+```
+
+---
+
+## 🎮 Play
+
+Run it inside any git repository — no arguments needed:
+
+```bash
+gitquest
+```
+
+`python -m gitquest` works too.
+
+### Flags
+
+| Flag             | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `--path <repo>`  | Play on another repository (default: current directory).  |
+| `--seed <n>`     | Force a specific dungeon seed (default: derived from repo).|
+| `--fast`         | Skip animations and "press Enter" pauses.                 |
+| `--stats-only`   | Skip gameplay and print just the flex card.               |
+| `--max-commits`  | Cap/sample commits for huge repos (default: 300).         |
+| `--version`      | Print the version.                                        |
+
+Examples:
+
+```bash
+gitquest --path ../some-other-repo
+gitquest --seed 42 --fast
+gitquest --stats-only        # instant career card, no fighting
+```
+
+---
+
+## 🧠 How it works
+
+`gitquest` maps real repository data onto game mechanics:
+
+| Git data                              | Becomes…                                        |
+| ------------------------------------- | ----------------------------------------------- |
+| **Commit**                            | A room in the dungeon                           |
+| **Lines added/removed**               | Room size + monster difficulty                  |
+| **Merge commit**                      | A mini-boss room                                |
+| **Files changed**                     | Loot/items in the room                          |
+| **Commit author**                     | An ally/NPC you meet                            |
+| **Languages (by file extension)**     | Your skill tree / XP categories                 |
+| **Message keywords**                  | Enemy types (`fix` → Bug, `feat` → Feature…)    |
+| **Total repo stats**                  | Your final rank (e.g. *Senior Crusader*)        |
+
+### Determinism
+
+The dungeon seed is derived from the SHA of the repository's **first commit**
+(unless you pass `--seed`). All procedural generation — monster names, stats,
+loot rolls, room sizes — flows from that single seed via a `random.Random`
+instance with a fixed call order. The result: identical, reproducible dungeons
+that you and a teammate can compare.
+
+### Architecture
+
+```
+gitquest/
+  cli.py          # entry point + argument parsing (argparse)
+  git_parser.py   # extract & normalize commit data (GitPython + git CLI fallback)
+  generator.py    # commit data -> dungeon/rooms/monsters (seeded)
+  engine.py       # game loop, state, turn handling
+  combat.py       # combat math (pure, rng-driven, testable)
+  entities.py     # Player, Monster, Room, Item, Dungeon dataclasses
+  renderer.py     # all rich-based rendering
+  flexcard.py     # final shareable stats card + ranking
+  data/           # monster/item name lists, ranks, ascii art
+tests/            # pytest: parser, generator determinism, combat
+```
+
+Everything runs **locally and offline** — no network calls, ever.
+
+---
+
+## 🛠️ Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover history parsing, generator **determinism**, and combat logic.
+
+### Edge cases handled
+
+- Not a git repository → friendly error, no traceback.
+- Empty history / no commits → friendly nudge to commit first.
+- Huge repos → evenly down-sampled to `--max-commits` (still deterministic).
+- Missing `GitPython` → automatic fallback to the `git` CLI.
+
+---
+
+## 🤝 Contributing
+
+Issues and PRs welcome! Ideas: more monster archetypes, a `textual` dungeon map,
+achievements, or exporting the flex card as an image.
+
+## 📄 License
+
+MIT — see [`LICENSE`](LICENSE).

gitquest-0.1.0/README.md

@@ -0,0 +1,198 @@
+# gitquest 🗡️
+
+> **Your commits. Your dungeon. Your legend.**
+> Turn any git repository's history into a procedurally generated, playable
+> ASCII dungeon roguelike — right in your terminal.
+
+`gitquest` reads your repo's real commit history and deterministically builds a
+dungeon from it. Each commit becomes a room. Bug-fix commits spawn bugs. Merge
+commits become mini-bosses. The languages you've coded fill your skill tree.
+Clear every room from the repo's first commit to `HEAD`, then flex your career
+on a shareable stats card.
+
+**Same repo + same seed = the same dungeon, every time.** Reproducible and
+shareable.
+
+---
+
+## ✨ Demo
+
+<!--
+  📽️  ANIMATED GIF PLACEHOLDER
+  Drop a terminal recording here (e.g. via `asciinema` + `agg`, or a screen GIF).
+  Recommended: a ~20s clip of a fight + the final flex card.
+  ![gitquest demo](docs/demo.gif)
+-->
+
+```text
+   ____ _ _    ___                  _
+  / ___(_) |_ / _ \ _   _  ___  ___| |_
+ | |  _| | __| | | | | | |/ _ \/ __| __|
+ | |_| | | |_| |_| | |_| |  __/\__ \ |_
+  \____|_|\__|\__\_\\__,_|\___||___/\__|
+
+      Your commits. Your dungeon. Your legend.
+
+┌───────────────────────────────── Room 2/5 ──────────────────────────────────┐
+│ fix: bug in output handling                                                  │
+│ 33b27d3 · +2/-0 · a tight crawlspace of tangled diffs                        │
+│ 🧙 You meet Ada Lovelace, an ally from this commit.                          │
+└──────────────────────────────────────────────────────────────────────────────┘
+🧠 Skill XP: +1 Python, +1 JavaScript
+┌────────────────────────────── A Bug appears! ───────────────────────────────┐
+│                          (>_<)                                               │
+│                          Off-by-One                                          │
+│                          HP 11  ·  ATK 4  ·  DEF 0                           │
+└──────────────────────────────────────────────────────────────────────────────┘
+Attack  Defend  Item(0)  Run
+Your move (a): » Hero hits Off-by-One for 6 damage.
+✔ Off-by-One defeated! (+10 XP, +6 gold)
+```
+
+And the grand finale — the shareable **flex card**:
+
+```text
+┌───────────────────────────────── flex card ─────────────────────────────────┐
+│                    ⚔  GITQUEST CAREER CARD  ⚔                                │
+│                    my-repo   seed 17391773614721965407                       │
+│                                                                              │
+│     RANK: Senior Crusader                                                    │
+│     SCORE: 2310                                                              │
+│     STATUS: VICTORIOUS                                                        │
+│                                                                              │
+│     CAREER STATS                                                             │
+│       Level   11              Gold   642                                     │
+│       Kills   148           Bosses   12                                      │
+│     SKILL TREE                                                               │
+│   Python      ██████████████████ 220                                         │
+│   TypeScript  ███████████░░░░░░░ 130                                         │
+│     Specialization: Python  ·  6 skill paths explored                        │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Install
+
+The zero-friction way (isolated, recommended):
+
+```bash
+pipx install gitquest
+```
+
+Or with pip:
+
+```bash
+pip install gitquest
+```
+
+From source:
+
+```bash
+git clone https://github.com/jithin-jz/gitquest
+cd gitquest
+pip install .
+```
+
+---
+
+## 🎮 Play
+
+Run it inside any git repository — no arguments needed:
+
+```bash
+gitquest
+```
+
+`python -m gitquest` works too.
+
+### Flags
+
+| Flag             | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `--path <repo>`  | Play on another repository (default: current directory).  |
+| `--seed <n>`     | Force a specific dungeon seed (default: derived from repo).|
+| `--fast`         | Skip animations and "press Enter" pauses.                 |
+| `--stats-only`   | Skip gameplay and print just the flex card.               |
+| `--max-commits`  | Cap/sample commits for huge repos (default: 300).         |
+| `--version`      | Print the version.                                        |
+
+Examples:
+
+```bash
+gitquest --path ../some-other-repo
+gitquest --seed 42 --fast
+gitquest --stats-only        # instant career card, no fighting
+```
+
+---
+
+## 🧠 How it works
+
+`gitquest` maps real repository data onto game mechanics:
+
+| Git data                              | Becomes…                                        |
+| ------------------------------------- | ----------------------------------------------- |
+| **Commit**                            | A room in the dungeon                           |
+| **Lines added/removed**               | Room size + monster difficulty                  |
+| **Merge commit**                      | A mini-boss room                                |
+| **Files changed**                     | Loot/items in the room                          |
+| **Commit author**                     | An ally/NPC you meet                            |
+| **Languages (by file extension)**     | Your skill tree / XP categories                 |
+| **Message keywords**                  | Enemy types (`fix` → Bug, `feat` → Feature…)    |
+| **Total repo stats**                  | Your final rank (e.g. *Senior Crusader*)        |
+
+### Determinism
+
+The dungeon seed is derived from the SHA of the repository's **first commit**
+(unless you pass `--seed`). All procedural generation — monster names, stats,
+loot rolls, room sizes — flows from that single seed via a `random.Random`
+instance with a fixed call order. The result: identical, reproducible dungeons
+that you and a teammate can compare.
+
+### Architecture
+
+```
+gitquest/
+  cli.py          # entry point + argument parsing (argparse)
+  git_parser.py   # extract & normalize commit data (GitPython + git CLI fallback)
+  generator.py    # commit data -> dungeon/rooms/monsters (seeded)
+  engine.py       # game loop, state, turn handling
+  combat.py       # combat math (pure, rng-driven, testable)
+  entities.py     # Player, Monster, Room, Item, Dungeon dataclasses
+  renderer.py     # all rich-based rendering
+  flexcard.py     # final shareable stats card + ranking
+  data/           # monster/item name lists, ranks, ascii art
+tests/            # pytest: parser, generator determinism, combat
+```
+
+Everything runs **locally and offline** — no network calls, ever.
+
+---
+
+## 🛠️ Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover history parsing, generator **determinism**, and combat logic.
+
+### Edge cases handled
+
+- Not a git repository → friendly error, no traceback.
+- Empty history / no commits → friendly nudge to commit first.
+- Huge repos → evenly down-sampled to `--max-commits` (still deterministic).
+- Missing `GitPython` → automatic fallback to the `git` CLI.
+
+---
+
+## 🤝 Contributing
+
+Issues and PRs welcome! Ideas: more monster archetypes, a `textual` dungeon map,
+achievements, or exporting the flex card as an image.
+
+## 📄 License
+
+MIT — see [`LICENSE`](LICENSE).

gitquest-0.1.0/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-0.1.0/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-0.1.0/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())