PatchTutor

Generate coding lessons from real merged pull requests.

PatchTutor turns a merged PR, commit range, or patch into a lesson pack with background, starter files, hints, and checks. The MVP is intentionally scoped to local JavaScript and TypeScript repositories so authors can keep lesson quality high.

Why This Exists

Most coding practice strips away the engineering context that made the bug interesting. PatchTutor keeps the patch shape, the file context, and the reviewable artifact, then wraps it in a static browser player that is easy to publish on GitHub Pages.

Features

• Generate lesson packs from a local git repository and commit range.
• Filter for teachable JS/TS patches with bounded diff size.
• Write lesson-pack.json plus starter files.
• Play sample lessons in a static React app.
• Reveal hints progressively and show visible plus hidden checks.
• Package the demo site and sample lessons as a release zip.

Quick Start

npm install
npm run dev

Open the local Vite URL and visit /patchtutor/.

Generate a Lesson Pack

npm run generate -- --repo ../some-js-repo --range abc123..def456 --out lessons/generated/my-lesson

The generator writes:

• lesson-pack.json
• starter/<changed-file-path> for starter snapshot files

Online Demo

GitHub Pages is configured for artifact deployment. After the repository is published, the demo will be available at:

https://kanadek.github.io/patchtutor/

Repository Structure

patchtutor/
├─ apps/web/              Static React player
├─ packages/generator/    Git diff to lesson-pack engine
├─ packages/player/       Lesson types and browser runner helpers
├─ lessons/samples/       Handcrafted sample lesson packs
├─ tests/unit/            Parser, generator, and player tests
├─ tests/e2e/             Browser player smoke test
├─ scripts/               Bootstrap, check, test, build, demo, release
└─ media/demo.png         Generated demo screenshot

Architecture

Input: local git repo plus a commit range.

Core processing: packages/generator reads the diff, filters JS/TS files, captures starter and target file contents, builds a hint ladder, and serializes a lesson pack.

Output: portable JSON and starter files that can be reviewed, edited, zipped, and rendered by the static player.

Quality Gates

bash scripts/check.sh
bash scripts/test.sh
bash scripts/build.sh
bash scripts/demo.sh
RELEASE_TAG=v0.1.0 bash scripts/build_release.sh

License Suitability Warning

Not every open source patch is suitable lesson material. Before publishing generated lessons from a third-party repository:

• Confirm the source repository license.
• Record source repository, commit range, and license in the lesson pack.
• Avoid private data, secrets, unreleased security fixes, or copyrighted prose that cannot be redistributed.
• Prefer self-authored fixtures or repositories with clear permissive licenses for public examples.

Code in this repository is MIT licensed. Sample lesson content is CC-BY-4.0 unless a lesson pack states otherwise.

Roadmap

• Author review UI for editing generated lesson copy.
• Better test mapping from source repository test files.
• Difficulty scoring based on semantic patch shape.
• Course pack export with ordered lesson paths.
• Optional bilingual lesson notes.

Release

RELEASE_TAG=v0.1.0 bash scripts/build_release.sh

The archive is written to release/patchtutor-v0.1.0.zip.