Upgrade repo for recruiter visibility with CI and tests

Author: Kyle Parker

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run unit tests
+        run: python -m unittest discover -s tests -p "test_*.py" -v

CAREER_VISIBILITY.md

@@ -0,0 +1,29 @@
+# Career Visibility Checklist
+
+Use this checklist to improve discovery by recruiters hiring for Business Analyst, Data Scientist, and AI roles.
+
+## GitHub repository settings
+- Add the repository description from `README.md`.
+- Add topics: `python`, `sql`, `sqlite`, `business-analyst`, `data-science`, `machine-learning`, `ai`, `education`.
+- Pin this repo on your GitHub profile.
+- Enable "Discussions" if you want community feedback and activity signals.
+
+## GitHub profile optimization
+- Update profile headline with target roles and keywords.
+- Add a profile README with:
+  - Short bio and target roles.
+  - Top skills (Python, SQL, analytics, ML basics).
+  - 3 pinned projects with business impact statements.
+- Link LinkedIn and portfolio site in profile links.
+
+## Employer-ready proof points
+- Add a short demo GIF/screenshot in the README.
+- Add metrics after updates (for example: number of challenges, test coverage, CI status).
+- Add a "Case Study" section describing problem, approach, and outcome.
+
+## Networking strategy
+- Share the repo on LinkedIn with a short post describing:
+  - Who it helps.
+  - What technical decisions you made.
+  - What you plan to improve next.
+- Ask for peer feedback and create follow-up commits based on comments.

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+Thanks for your interest in improving Code Quest.
+
+## Development setup
+```bash
+cd "/Users/kyleparker/Documents/code game"
+python3 -m unittest discover -s tests -p "test_*.py" -v
+python3 main.py
+```
+
+## Contribution guidelines
+- Keep changes focused and documented.
+- Add or update tests for behavior changes.
+- Keep the beginner-learning experience clear and simple.
+- Use descriptive commit messages.

README.md

@@ -1,39 +1,69 @@
 # Code Quest: Python + SQL Trainer
 
-Learn Python and SQL by playing short, interactive coding challenges.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![CI](https://img.shields.io/badge/tests-unittest-green.svg)](.github/workflows/ci.yml)
 
-> GitHub tagline: Beginner-friendly Python + SQL learning game with interactive challenges, hints, and progress tracking.
+Code Quest is a beginner-friendly command-line learning game for Python and SQL. It uses interactive challenges, instant feedback, and progress tracking to help users build practical coding and query skills.
 
-Code Quest is a beginner-focused terminal app designed to make coding practice feel like a game. Players solve Python and SQL tasks, get instant feedback, and build confidence step by step. SQL challenges run on a real SQLite dataset, so learners practice query skills they can actually use.
+## Why this project matters
+- Demonstrates Python programming fundamentals (`dataclasses`, validation logic, file persistence).
+- Demonstrates SQL competency using real query execution with SQLite.
+- Shows product thinking: gamification, hinting, progression, and user feedback loops.
+- Shows software engineering basics: tests, CI workflow, repo documentation, and MIT licensing.
 
-## GitHub About (Recommended)
-- Description: Beginner-friendly Python + SQL learning game with interactive challenges, hints, and progress tracking.
-- Website: https://github.com/kp147852-droid/Code-Quest-Python-SQL-Trainer
-- Topics: python, sql, sqlite, education, cli-game, beginner-friendly, learning-by-doing
+## Role relevance (for hiring)
+- Business Analyst: SQL filtering/aggregation patterns, data reasoning, and clear user flows.
+- Data Scientist: data manipulation mindset, query literacy, and iterative problem solving.
+- AI/ML Roles: core coding fluency, debugging discipline, and structured evaluation logic.
+
+## Features
+- Python challenge mode with retry + hint support.
+- SQL challenge mode with executable queries against an in-memory SQLite dataset.
+- Scoring system (+10 Python, +15 SQL) and unlocked progression.
+- Local progress persistence in `progress.json`.
+- Reset option for repeated practice.
 
-## What it does
-- Gives step-by-step Python challenges.
-- Gives SQL challenges against a real SQLite dataset.
-- Tracks score and progress in `progress.json`.
-- Lets players retry with hints.
+## Tech stack
+- Python 3
+- SQLite (standard library `sqlite3`)
+- JSON persistence
+- GitHub Actions-ready CI configuration
 
-## Run
+## Quick start
 ```bash
 cd "/Users/kyleparker/Documents/code game"
 python3 main.py
 ```
 
-## Game flow
+## Example game loop
 1. Pick Python or SQL challenge.
-2. Enter your answer/query.
-3. Get instant feedback and hints.
-4. Earn points and unlock the next challenge.
+2. Submit answer or SQL query.
+3. Receive immediate feedback (and hints if needed).
+4. Earn points and continue to the next level.
+
+## Repository structure
+- `main.py` - menu and game loop.
+- `game.py` - challenge logic, scoring, SQLite setup, persistence.
+- `tests/test_game.py` - unit tests for core behavior.
+- `.github/workflows/ci.yml` - automated test run on push/PR.
+
+## Suggested GitHub "About" settings
+- Description: Beginner-friendly Python + SQL learning game with interactive challenges, hints, and progress tracking.
+- Website: <YOUR_PORTFOLIO_OR_LINKEDIN_URL>
+- Topics: `python`, `sql`, `sqlite`, `business-analyst`, `data-science`, `ai-learning`, `education`, `cli-game`
+
+## Portfolio talking points
+- Built an educational CLI product that maps technical exercises to measurable progression.
+- Designed challenge validation logic for both Python and SQL with constrained retries and hints.
+- Added test coverage and CI to keep behavior reliable as feature scope grows.
+- Documented recruiter-discovery steps in [CAREER_VISIBILITY.md](CAREER_VISIBILITY.md).
 
-## Ideas to expand
-- Add more levels and difficulty modes.
-- Add timer/leaderboard features.
-- Add multiplayer quiz mode.
-- Add web UI (Flask/Streamlit) later.
+## Roadmap
+- Add intermediate and advanced challenge packs.
+- Add analytics export (CSV) for learner performance tracking.
+- Add optional web UI (Streamlit or Flask).
+- Add LLM-assisted hints for dynamic coaching.
 
 ## License
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file.

tests/test_game.py

@@ -0,0 +1,63 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+import game
+
+
+class TestGame(unittest.TestCase):
+    def test_default_python_challenges_count(self):
+        challenges = game.default_python_challenges()
+        self.assertEqual(len(challenges), 3)
+
+    def test_default_sql_challenges_count(self):
+        challenges = game.default_sql_challenges()
+        self.assertEqual(len(challenges), 3)
+
+    def test_sql_database_seeded(self):
+        conn = game.setup_sql_db()
+        rows = conn.execute("SELECT COUNT(*) FROM learners").fetchone()
+        conn.close()
+        self.assertEqual(rows[0], 4)
+
+    def test_progress_save_and_load(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            original = game.PROGRESS_FILE
+            try:
+                game.PROGRESS_FILE = Path(temp_dir) / "progress.json"
+                payload = {"python_done": 2, "sql_done": 1, "score": 35}
+                game.save_progress(payload)
+                loaded = game.load_progress()
+                self.assertEqual(loaded, payload)
+            finally:
+                game.PROGRESS_FILE = original
+
+    def test_progress_invalid_json_fallback(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            original = game.PROGRESS_FILE
+            try:
+                game.PROGRESS_FILE = Path(temp_dir) / "progress.json"
+                game.PROGRESS_FILE.write_text("{not-json", encoding="utf-8")
+                loaded = game.load_progress()
+                self.assertEqual(loaded, {"python_done": 0, "sql_done": 0, "score": 0})
+            finally:
+                game.PROGRESS_FILE = original
+
+    def test_progress_type_fallback(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            original = game.PROGRESS_FILE
+            try:
+                game.PROGRESS_FILE = Path(temp_dir) / "progress.json"
+                game.PROGRESS_FILE.write_text(
+                    json.dumps({"python_done": "x", "sql_done": 2, "score": 10}),
+                    encoding="utf-8",
+                )
+                loaded = game.load_progress()
+                self.assertEqual(loaded, {"python_done": 0, "sql_done": 0, "score": 0})
+            finally:
+                game.PROGRESS_FILE = original
+
+
+if __name__ == "__main__":
+    unittest.main()