From 133c678b4fdd896a49bdf399f063ddc9da8ff450 Mon Sep 17 00:00:00 2001 From: shilpijc Date: Mon, 3 Aug 2026 00:43:17 +0530 Subject: [PATCH] Rename package to code-explainer 3.0 with pr and repo modes. Ship @shilpi1958/code-explainer with explicit subcommands, keep pr-explainer as a legacy alias, document Graphify for repo mode, and refresh the site without the Product Hunt badge. Co-authored-by: Cursor --- README.md | 223 ++++++++------------------ action.yml | 8 +- docs/index.html | 132 ++++----------- package-lock.json | 9 +- package.json | 11 +- src/cli.js | 157 +++++++++++++----- src/github.js | 6 +- src/posthog.js | 20 ++- templates/learning-profile.example.md | 7 +- test/posthog.test.js | 2 + 10 files changed, 259 insertions(+), 316 deletions(-) diff --git a/README.md b/README.md index 1755bb3..9db52e1 100644 --- a/README.md +++ b/README.md @@ -1,192 +1,111 @@ -# pr-explainer - -Point it at any merged pull request, anywhere on GitHub. Get back a -plain explainer of what it did and why it matters — pitched at *you*, -whoever you are — plus a couple of quick questions to check it stuck. - -You don't need to have written the PR, or even read code. A product -analyst can point it at an engineer's PR and get a stakeholder-ready -explanation with zero jargon. An engineer can point it at a teammate's -PR and get the reasoning, not just the diff. Same tool — the only -input that changes is a one-time profile describing who's reading. - -## How it works - -1. Run `pr-explainer init` once — it creates - `~/.pr-explainer/learning-profile.md`. Edit it with your role and - what you're currently trying to understand better. Not a skills - checklist, just a couple of sentences. That one file applies - everywhere you run the CLI. -2. Point the CLI at any merged PR — a number, a URL, whatever `gh pr - view` accepts. It reads the PR's diff and description, combines it - with your profile, and asks Claude to write one plain-language - explainer: what changed, why it was done this way, why it matters - to you — followed by a multiple-choice Quick check. -3. The explainer lands in `~/.pr-explainer/explainers/`, and gets added - to a running `index.md` of every PR you've explained so far. A readable - summary (title, Ships, What changed, Why it was done this way, Why it - matters) prints to the terminal first. In an interactive terminal, press - Enter for a CHECK IT STUCK quiz (pick A/B/C, Enter to skip, `q` to quit), - then optionally open the saved file. - -## Quick start (CLI) +# code-explainer + +Plain-language explainers for **merged GitHub PRs** or a **whole repository** — +pitched at *you*, via a one-time learning profile. Optional interactive quiz +so it sticks. ```bash -npm install -g @shilpi1958/pr-explainer -pr-explainer init -# edit ~/.pr-explainer/learning-profile.md to describe yourself - -pr-explainer 42 # current repo only -pr-explainer https://github.com/some-org/some-repo/pull/42 # any repo -pr-explainer some-org/some-repo#42 -pr-explainer https://github.com/some-org/some-repo/pull/42 --no-quiz - -# Explain a whole local checkout (needs Graphify — see below) -pr-explainer repo -pr-explainer repo /path/to/checkout --no-quiz +npm install -g @shilpi1958/code-explainer + +code-explainer init +# edit ~/.code-explainer/learning-profile.md (or legacy ~/.pr-explainer/) + +code-explainer pr https://github.com/org/repo/pull/42 +code-explainer repo # explain the checkout you're in ``` -### Repo mode +The `pr-explainer` binary is still installed as an alias (legacy shorthand: +`pr-explainer ` without the `pr` subcommand). -`pr-explainer repo` orients you to what a **repository** does — for non-engineers -or engineers outside that domain — using the same learning profile as PR mode. +## Modes -It builds a local [Graphify](https://graphify.com/) knowledge graph of the -checkout (structure, hubs, communities), combines that with recent merged PRs -and your profile, and writes a concise plain-language explainer. Output lands -in `~/.pr-explainer/explainers/repos/`. +### `pr` — what just shipped -Requires a **local git checkout** with a GitHub remote (not a bare `owner/repo` -URL yet), plus Graphify: +Point it at any merged PR (number, URL, or `owner/repo#N`). Reads the diff + +description, combines it with your profile, and asks Claude Code for a +plain-language explainer. ```bash -uv tool install graphifyy # or: pipx install graphifyy +code-explainer pr 42 +code-explainer pr https://github.com/org/repo/pull/42 +code-explainer pr org/repo#42 --no-quiz ``` -If `graphify` is missing, repo mode exits with install instructions. - -> **Note:** a bare number resolves against the GitHub repo of your current -> directory. To explain a PR elsewhere, pass the full URL or `owner/repo#N`. -> Only **merged** PRs are supported. - -After the explainer is saved, a summary of the key sections prints to stderr -(title, Ships, What changed, Why it was done this way, Why it matters — Quick -check is left for the quiz). In an interactive terminal you’re prompted -`Press Enter for CHECK IT STUCK…`, then the multiple-choice quiz runs -(`a`/`b`/`c` or `1`/`2`/`3`, Enter to skip, `q` to quit early). Correct picks -get a green ✓; wrong picks show the right option. Then you’re offered -`Open explainer? [y/N]`. The Markdown file still keeps the questions with -options and collapsed answers for later. Pass `--no-quiz` (or set -`PR_EXPLAINER_NO_QUIZ=1`) to skip the quiz; it’s also skipped when stdin -isn’t a TTY (CI, pipes). The summary still prints unless -`PR_EXPLAINER_QUIET=1`. The only stdout line is the saved file path (for -scripting). - -No API key needed if you already have [Claude Code](https://claude.com/claude-code) -installed and logged in — `pr-explainer` calls the local `claude` CLI, so it -rides on whatever auth you already use there (subscription or key). Run `claude` -once to log in if you haven't. - -Also requires the [GitHub CLI](https://cli.github.com/) (`gh`), authenticated -(`gh auth login`). - -**Repo mode** additionally requires [Graphify](https://graphify.com/docs) -(`uv tool install graphifyy`). -## GitHub Action (optional) - -The CLI is the main way to use this — point it at any PR, any time. The -Action is for the narrower case of auto-generating an explainer for your -*own* repo's PRs as they merge, committed automatically. +### `repo` — what this codebase is -CI runners don't have access to your local `claude` login, so the Action -needs a credential. If you have a Claude subscription, generate a -long-lived token once, locally: +Orients non-engineers (or engineers in another domain) to a **local** checkout. +Builds a [Graphify](https://graphify.com/) knowledge graph, adds recent merges + +your profile, and writes a concise orientation. ```bash -claude setup-token -gh secret set CLAUDE_CODE_OAUTH_TOKEN +# also required for repo mode: +uv tool install graphifyy # or: pipx install graphifyy + +cd /path/to/checkout +code-explainer repo +code-explainer repo --no-quiz ``` -Then drop this into `.github/workflows/explainer.yml`: +If `graphify` is missing, repo mode exits with install instructions. -```yaml -on: - pull_request: - types: [closed] - -jobs: - explainer: - if: github.event.pull_request.merged == true - runs-on: ubuntu-latest - permissions: - contents: write - steps: - - uses: actions/checkout@v4 - with: - ref: ${{ github.event.pull_request.base.ref }} - - uses: shilpi1958/pr-explainer@v1 - with: - claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} -``` +## Requirements -No subscription? Pass `anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}` -instead (Console API key, billed separately). +- [Claude Code](https://claude.com/claude-code) CLI (`claude`), logged in +- [GitHub CLI](https://cli.github.com/) (`gh`), authenticated +- **Repo mode only:** [Graphify](https://graphify.com/docs) (`uv tool install graphifyy`) -Every merge gets you a commit with a fresh explainer. Put a -`learning-profile.md` in the repo root for the Action (or pass -`profile-path`); explainers are written to `docs/explainers/` by default. +No separate Anthropic API key for local use — the tool shells out to `claude`. -## Configuration +## Profile + +```bash +code-explainer init +``` -Profile lookup (first hit wins): +Creates `~/.code-explainer/learning-profile.md` (or keeps using +`~/.pr-explainer/` if you already have one). Override with `LEARNING_PROFILE` +or a local `./learning-profile.md`. -1. `LEARNING_PROFILE` env -2. `./learning-profile.md` (repo override — useful for the Action) -3. `~/.pr-explainer/learning-profile.md` (default for local CLI) +## Output -| Env var | Default | Purpose | -|---|---|---| -| `LEARNING_PROFILE` | `~/.pr-explainer/learning-profile.md` | path to your profile | -| `EXPLAINER_DIR` | `~/.pr-explainer/explainers` | output directory | -| `PR_EXPLAINER_NO_QUIZ` | unset | set to `1` to skip the interactive quiz | -| `PR_EXPLAINER_QUIET` | unset | set to `1` to skip printing the summary to stderr | -| `POSTHOG_API_KEY` | unset | enables product analytics + `$ai_generation` for [PostHog AI Evals](https://posthog.com/docs/ai-evals). Alias: `POSTHOG_PROJECT_TOKEN` | -| `POSTHOG_HOST` | PostHog default | e.g. `https://us.i.posthog.com` | -| `POSTHOG_DEBUG` | unset | set to `1` to log when PostHog is unconfigured | +- PR explainers → `~/.code-explainer/explainers/` (or legacy path) +- Repo explainers → `…/explainers/repos/` +- Summary prints to stderr; quiz is interactive unless `--no-quiz` / + `PR_EXPLAINER_NO_QUIZ=1` -Copy [`.env.example`](.env.example) to `.env` for local runs (loaded automatically from cwd or package root). For the GitHub Action, pass `posthog-api-key` / `posthog-host` inputs (see `action.yml`) via repo secrets — not only a local `.env`. +## GitHub Action (optional) -When configured, the CLI emits `profile_initialized`, `explainer_generation_started`, `explainer_generated`, plus `$ai_generation` (for evals) and mode-specific `pr_explained` / `repo_explained`. +Auto-generate a PR explainer on merge. Pass Claude credentials and optional +PostHog secrets: -See [`templates/learning-profile.example.md`](templates/learning-profile.example.md) -for the profile format. +```yaml +- uses: shilpi1958/pr-explainer@v1 + with: + claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + posthog-api-key: ${{ secrets.POSTHOG_API_KEY }} + posthog-host: ${{ secrets.POSTHOG_HOST }} +``` -## Why this needs no separate API key (locally) +## Analytics (optional) -`pr-explainer` shells out to the `claude` CLI instead of calling the -Anthropic API directly. If you already use Claude Code, you already have -auth configured — nothing new to sign up for, no data leaving your -machine except what `claude` itself sends. +Copy [`.env.example`](.env.example) to `.env` for local PostHog capture +(`POSTHOG_API_KEY` / `POSTHOG_PROJECT_TOKEN` + `POSTHOG_HOST`). Enables +funnel events and `$ai_generation` for [AI Evals](https://posthog.com/docs/ai-evals). ## Troubleshooting | Symptom | Fix | |---|---| -| `No profile found` | Run `pr-explainer init`, then edit `~/.pr-explainer/learning-profile.md` | -| `Could not resolve to a PullRequest` / PR not found | A bare number only looks in the **current** repo. Pass a URL or `owner/repo#42` | -| `PR … is not merged yet` | Only merged PRs are supported — pick one that already shipped | -| `claude -p failed` / spending cap / usage limit | Wait for the Claude Code reset, raise your cap, or retry later. Confirm `claude` works on its own | -| Claude Code CLI not found | Install from https://claude.com/claude-code and run `claude` once to log in | -| `gh` auth / forbidden errors | Run `gh auth login` | -| GitHub CLI not found | Install from https://cli.github.com/ | -| Graphify CLI not found / repo mode | Install with `uv tool install graphifyy`, then retry `pr-explainer repo` | - -Quick sanity checks: +| `No profile found` | `code-explainer init`, then edit the profile file | +| Bare PR number not found | `cd` into the repo, or pass a URL / `owner/repo#N` | +| PR not merged | Only merged PRs are supported | +| Graphify not found | `uv tool install graphifyy` | +| Claude / gh auth | Run `claude` once; `gh auth login` | ```bash gh auth status claude -p --output-format text <<< "Say hi in one word" -pr-explainer --help +code-explainer --help ``` ## License diff --git a/action.yml b/action.yml index 556d081..b9ea6df 100644 --- a/action.yml +++ b/action.yml @@ -45,10 +45,10 @@ runs: with: node-version: "20" - - name: Install pr-explainer and Claude Code CLI + - name: Install code-explainer and Claude Code CLI shell: bash run: | - npm install --no-save @shilpi1958/pr-explainer @anthropic-ai/claude-code + npm install --no-save @shilpi1958/code-explainer @anthropic-ai/claude-code - name: Generate explainer id: generate @@ -62,14 +62,14 @@ runs: POSTHOG_API_KEY: ${{ inputs.posthog-api-key }} POSTHOG_HOST: ${{ inputs.posthog-host }} run: | - OUT_PATH=$(npx pr-explainer "${{ github.event.pull_request.number }}") + OUT_PATH=$(npx code-explainer pr "${{ github.event.pull_request.number }}") echo "path=$OUT_PATH" >> "$GITHUB_OUTPUT" - name: Commit entry if: ${{ inputs.commit == 'true' }} shell: bash run: | - git config user.name "pr-explainer[bot]" + git config user.name "code-explainer[bot]" git config user.email "actions@github.com" git add "${{ steps.generate.outputs.path }}" "$(dirname "${{ steps.generate.outputs.path }}")/index.md" git commit -m "docs: explainer for #${{ github.event.pull_request.number }}" diff --git a/docs/index.html b/docs/index.html index d1e25af..96a20d5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -3,11 +3,11 @@ -pr-explainer — plain-English explainers for any GitHub PR - +code-explainer — plain-English explainers for PRs and repos + - - + + @@ -136,66 +136,6 @@ .btn-secondary { border: 1px solid var(--border-strong); color: var(--text); } .btn-secondary:hover { border-color: var(--text-muted); } - .ph-badge { - margin: 36px auto 0; - max-width: 500px; - text-align: left; - font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; - border: 1px solid rgb(224, 224, 224); - border-radius: 12px; - padding: 20px; - background: rgb(255, 255, 255); - box-shadow: rgba(0, 0, 0, 0.05) 0px 2px 8px; - } - .ph-badge-top { - display: flex; - align-items: center; - gap: 12px; - margin-bottom: 12px; - } - .ph-badge-top img { - width: 64px; - height: 64px; - border-radius: 8px; - object-fit: cover; - flex-shrink: 0; - } - .ph-badge-copy { flex: 1 1 0%; min-width: 0; } - .ph-badge-copy h3 { - margin: 0; - font-size: 18px; - font-weight: 600; - color: rgb(26, 26, 26); - line-height: 1.3; - overflow: hidden; - text-overflow: ellipsis; - white-space: nowrap; - } - .ph-badge-copy p { - margin: 4px 0 0; - font-size: 14px; - color: rgb(102, 102, 102); - line-height: 1.4; - overflow: hidden; - text-overflow: ellipsis; - display: -webkit-box; - -webkit-line-clamp: 2; - -webkit-box-orient: vertical; - } - .ph-badge a.ph-cta { - display: inline-flex; - align-items: center; - gap: 4px; - margin-top: 12px; - padding: 8px 16px; - background: rgb(255, 97, 84); - color: rgb(255, 255, 255); - text-decoration: none; - border-radius: 8px; - font-size: 14px; - font-weight: 600; - } - /* section shared */ section.block { padding: 70px 40px; @@ -372,7 +312,7 @@ - pr-explainer + code-explainer
How it works @@ -383,60 +323,50 @@
NO SEPARATE API KEY · CLAUDE CODE + GH · FREE & OPEN SOURCE
-

Point it at a merged PR.
Get a plain-English explanation.

+

Explain a PR or a whole repo
in plain English.

Calibrated to whoever's reading — technical or not — plus an interactive CLI quiz to check it stuck.

-
$ npm install -g @shilpi1958/pr-explainer
+
$ npm install -g @shilpi1958/code-explainer
View on GitHub Read the docs
-
-
- PR Explainer -
-

PR Explainer

-

Understand any GitHub PR, even if you don't write code

-
-
- Check it out on Product Hunt → -

THE CODE IS THE TRUTH

-

Docs go stale. Slack answers depend on who you ask. The code, right now, at this commit, is just true. The problem was never access to that truth — anyone can open a diff. It was translation. pr-explainer reads the reasoning behind a change and explains it in language pitched at whoever's asking.

+

Docs go stale. Slack answers depend on who you ask. The code, right now, at this commit, is just true. The problem was never access — anyone can open a diff or a tree. It was translation. code-explainer reads what shipped (or what a repo is) and explains it in language pitched at whoever's asking.

HOW IT WORKS

-

Init once. Then one command per PR.

+

Init once. Then pr for a change, or repo for the whole codebase.

01
-
Run pr-explainer init once — edit ~/.pr-explainer/learning-profile.md with your role and what you're trying to understand.
+
Run code-explainer init once — edit ~/.code-explainer/learning-profile.md with your role and what you're trying to understand.
02
-
Run it against any merged PR — a number, a URL, or owner/repo#123.
+
PR mode: code-explainer pr against any merged PR — a number, URL, or owner/repo#123.
03
-
It reads the diff + description via the GitHub CLI, combines it with your profile, and shells out to the Claude Code CLI to explain it.
+
Repo mode: code-explainer repo in a local checkout. Needs Graphify (uv tool install graphifyy) to map the code.
04
-
Saved under ~/.pr-explainer/explainers/, summary prints in the terminal, then a CHECK IT STUCK quiz — pick A/B/C, see ✓ correct.
+
Summary prints in the terminal, file is saved, then a CHECK IT STUCK quiz — pick A/B/C, see ✓ correct.
-
$ pr-explainer https://github.com/facebook/react/pull/32
+
$ code-explainer pr https://github.com/facebook/react/pull/32
Generating explainer for PR #32: Add new onInput event
-
~/.pr-explainer/explainers/01-react-now-responds-to-text-input-changes-faster-and-more-rel.md
+
~/.code-explainer/explainers/01-react-now-responds-to-text-input-changes-faster-and-more-rel.md
React now responds to input changes faster and more reliably
Ships: The framework now supports the onInput event…
@@ -470,18 +400,18 @@

WHO IT'S FOR

PM / ANALYST
-

Understand any PR, org-wide

-

Point it at an engineer's merged PR, get a stakeholder-ready explanation — no jargon, no pinging anyone.

+

Understand PRs and unfamiliar repos

+

Point it at a merged PR — or a whole checkout — and get a stakeholder-ready explanation without pinging anyone.

ENGINEER
-

Review outside your usual area

-

Get the reasoning behind a change in an unfamiliar part of the codebase, not just the mechanical diff.

+

Orient outside your usual area

+

Get the reasoning behind a change, or a map of a codebase you don't own, without reading every file.

MAINTAINER
-

Keep track of your own project

-

Including PRs an AI assistant pushed on your behalf — know exactly what shipped and why.

+

Keep track of what shipped

+

Including PRs an AI assistant pushed on your behalf — know exactly what changed and why.

@@ -489,7 +419,7 @@

Keep track of your own project

WHY NO API KEY

-

pr-explainer shells out to the Claude Code CLI already on your machine — if you already use it, this is free to try immediately. No separate Anthropic Console API key, no signup for this tool. You do need Claude Code installed and logged in, plus the GitHub CLI (gh).

+

code-explainer shells out to the Claude Code CLI already on your machine — if you already use it, this is free to try immediately. No separate Anthropic Console API key, no signup for this tool. You do need Claude Code installed and logged in, plus the GitHub CLI (gh). Repo mode also needs Graphify (uv tool install graphifyy).

@@ -497,15 +427,19 @@

WHY NO API KEY

INSTALL

# install
-
$ npm install -g @shilpi1958/pr-explainer
+
$ npm install -g @shilpi1958/code-explainer
# set up your profile once (applies everywhere)
-
$ pr-explainer init
-
$ # edit ~/.pr-explainer/learning-profile.md
+
$ code-explainer init
+
$ # edit ~/.code-explainer/learning-profile.md
+
+
# explain a merged PR
+
$ code-explainer pr owner/repo#123
+
$ code-explainer pr owner/repo#123 --no-quiz
-
# explain a PR (summary, then interactive quiz)
-
$ pr-explainer owner/repo#123
-
$ pr-explainer owner/repo#123 --no-quiz
+
# explain a whole local checkout (needs Graphify)
+
$ uv tool install graphifyy
+
$ code-explainer repo
@@ -513,7 +447,7 @@

INSTALL

MIT licensed · self-hosted · uses your local Claude Code + gh auth
GitHub - Product Hunt + npm
diff --git a/package-lock.json b/package-lock.json index f309ff2..540ee7a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,17 +1,18 @@ { - "name": "@shilpi1958/pr-explainer", - "version": "0.2.4", + "name": "@shilpi1958/code-explainer", + "version": "3.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "@shilpi1958/pr-explainer", - "version": "0.2.4", + "name": "@shilpi1958/code-explainer", + "version": "3.0.0", "license": "MIT", "dependencies": { "posthog-node": "^5.47.3" }, "bin": { + "code-explainer": "src/cli.js", "pr-explainer": "src/cli.js" }, "engines": { diff --git a/package.json b/package.json index 3da5a71..4716ff6 100644 --- a/package.json +++ b/package.json @@ -1,9 +1,10 @@ { - "name": "@shilpi1958/pr-explainer", - "version": "0.2.4", - "description": "Point it at any merged PR and get a plain explainer of what it did and why, pitched at you.", + "name": "@shilpi1958/code-explainer", + "version": "3.0.0", + "description": "Plain-language explainers for merged GitHub PRs or whole repos, pitched at your learning profile.", "type": "module", "bin": { + "code-explainer": "src/cli.js", "pr-explainer": "src/cli.js" }, "files": [ @@ -19,10 +20,12 @@ "github", "pull-request", "pr", + "repo", "explainer", "claude", "cli", - "documentation" + "documentation", + "code-explainer" ], "author": "shilpi1958", "repository": { diff --git a/src/cli.js b/src/cli.js index 6863f2e..d52a683 100755 --- a/src/cli.js +++ b/src/cli.js @@ -13,9 +13,9 @@ import { gatherRepoContext } from "./repo-context.js"; import { capture, captureAiGeneration, getDeviceId, shutdown } from "./posthog.js"; const MAX_DIFF_CHARS = 60_000; -const CONFIG_DIR = path.join(os.homedir(), ".pr-explainer"); -const GLOBAL_PROFILE = path.join(CONFIG_DIR, "learning-profile.md"); -const GLOBAL_EXPLAINERS = path.join(CONFIG_DIR, "explainers"); +const HOME = os.homedir(); +const NEW_CONFIG_DIR = path.join(HOME, ".code-explainer"); +const LEGACY_CONFIG_DIR = path.join(HOME, ".pr-explainer"); const LOCAL_PROFILE = "learning-profile.md"; const __dirname = path.dirname(fileURLToPath(import.meta.url)); @@ -26,44 +26,66 @@ const TEMPLATE_PATH = path.join( "learning-profile.example.md" ); +const invokedAs = path.basename(process.argv[1] || "code-explainer").replace( + /\.(js|mjs|cjs)$/i, + "" +); +const CLI_NAME = + invokedAs === "pr-explainer" || invokedAs === "code-explainer" + ? invokedAs + : "code-explainer"; +const isLegacyBin = CLI_NAME === "pr-explainer"; + +function resolveConfigDir() { + if (existsSync(NEW_CONFIG_DIR)) return NEW_CONFIG_DIR; + if (existsSync(LEGACY_CONFIG_DIR)) return LEGACY_CONFIG_DIR; + return NEW_CONFIG_DIR; +} + +function configPaths() { + const configDir = resolveConfigDir(); + return { + configDir, + globalProfile: path.join(configDir, "learning-profile.md"), + globalExplainers: path.join(configDir, "explainers"), + }; +} + function usage() { console.error( - `Usage: pr-explainer [--no-quiz] - pr-explainer repo [path] [--no-quiz] - pr-explainer init [--force] - -Explains merged pull requests — or a whole repository — in plain language, -tailored to your learning profile. Ends with a multiple-choice Quick check -so it's something you retain, not just read. + `Usage: ${CLI_NAME} init [--force] + ${CLI_NAME} pr [--no-quiz] + ${CLI_NAME} repo [path] [--no-quiz] +${ + isLegacyBin + ? ` ${CLI_NAME} [--no-quiz] (legacy shorthand for pr)\n` + : "" +} +Explain merged pull requests — or a whole repository — in plain language, +tailored to your learning profile. Ends with a multiple-choice Quick check. - PR a PR number ("42"), a PR URL, or "owner/repo#42" + init create ~/.code-explainer/learning-profile.md from the template + (falls back to ~/.pr-explainer/ if you already have one) + pr explain a merged PR: number ("42"), URL, or "owner/repo#42" (a bare number resolves against the repo in your current directory) - repo explain what a local git checkout does (cwd, or path to a checkout). - Uses Graphify to map the code, then writes a reader-pitched summary. - init create ~/.pr-explainer/learning-profile.md from the template - (use --force to overwrite an existing profile) - -After the explainer is saved, a readable summary prints to stderr. -In an interactive terminal: Press Enter, then CHECK IT STUCK quiz -(a/b/c or 1/2/3, Enter to skip, q to quit), then optionally open the -saved file. Pass --no-quiz to skip the quiz (also skipped in CI / -non-TTY). Summary still prints unless PR_EXPLAINER_QUIET=1. + repo explain what a local git checkout does (default: current directory). + Requires Graphify: uv tool install graphifyy Requires: - Claude Code CLI ("claude") installed and logged in - GitHub CLI ("gh") authenticated - - For repo mode: Graphify CLI ("graphify") — uv tool install graphifyy - -Profile lookup (first hit wins): - 1. LEARNING_PROFILE env - 2. ./learning-profile.md (repo override) - 3. ~/.pr-explainer/learning-profile.md (default) + - For repo mode: Graphify CLI ("graphify") Env: LEARNING_PROFILE optional path to profile file - EXPLAINER_DIR optional output dir (default: ~/.pr-explainer/explainers) + EXPLAINER_DIR optional output dir PR_EXPLAINER_NO_QUIZ set to 1 to skip the interactive quiz PR_EXPLAINER_QUIET set to 1 to skip printing the summary to stderr + +Install: + npm install -g @shilpi1958/code-explainer + # repo mode also needs: + uv tool install graphifyy ` ); } @@ -76,16 +98,25 @@ function parseArgs(argv) { else if (arg === "--no-quiz") flags.noQuiz = true; else if (arg === "--force") flags.force = true; else if (arg.startsWith("-")) { - throw new Error(`Unknown flag: ${arg}\nRun pr-explainer --help for usage.`); + throw new Error(`Unknown flag: ${arg}\nRun ${CLI_NAME} --help for usage.`); } else positionals.push(arg); } return { flags, positionals }; } +function looksLikePrRef(arg) { + if (!arg) return false; + if (/^\d+$/.test(arg)) return true; + if (/^https?:\/\//i.test(arg)) return true; + if (/^[^/\s]+\/[^#\s]+#\d+$/.test(arg)) return true; + return false; +} + function resolveProfilePath() { + const { globalProfile } = configPaths(); if (process.env.LEARNING_PROFILE) return process.env.LEARNING_PROFILE; if (existsSync(LOCAL_PROFILE)) return path.resolve(LOCAL_PROFILE); - return GLOBAL_PROFILE; + return globalProfile; } async function loadProfile() { @@ -94,12 +125,13 @@ async function loadProfile() { if (process.env.LEARNING_PROFILE) { throw new Error( `No profile found at LEARNING_PROFILE=${profilePath}.\n` + - `Fix that path, or unset LEARNING_PROFILE and run \`pr-explainer init\`.` + `Fix that path, or unset LEARNING_PROFILE and run \`${CLI_NAME} init\`.` ); } + const { globalProfile } = configPaths(); throw new Error( - `No profile found. Run \`pr-explainer init\`, then edit ` + - `${GLOBAL_PROFILE} to describe yourself.` + `No profile found. Run \`${CLI_NAME} init\`, then edit ` + + `${globalProfile} to describe yourself.` ); } const profile = await readFile(profilePath, "utf8"); @@ -116,19 +148,27 @@ async function initProfile(force = false) { if (!existsSync(TEMPLATE_PATH)) { throw new Error(`Template not found at ${TEMPLATE_PATH}`); } - await mkdir(CONFIG_DIR, { recursive: true }); - if (existsSync(GLOBAL_PROFILE) && !force) { + // Prefer creating under the new config dir going forward + const configDir = existsSync(LEGACY_CONFIG_DIR) && !existsSync(NEW_CONFIG_DIR) && !force + ? LEGACY_CONFIG_DIR + : NEW_CONFIG_DIR; + const globalProfile = path.join(configDir, "learning-profile.md"); + + await mkdir(configDir, { recursive: true }); + if (existsSync(globalProfile) && !force) { console.error( - `Profile already exists at ${GLOBAL_PROFILE}\n` + + `Profile already exists at ${globalProfile}\n` + `Edit it in place, or re-run with --force to overwrite from the template.` ); const deviceId = await getDeviceId(); capture("profile_initialized", deviceId, { force: false, created: false }); return; } - await copyFile(TEMPLATE_PATH, GLOBAL_PROFILE); - console.error(`Created ${GLOBAL_PROFILE}`); - console.error("Edit that file to describe your role, then run pr-explainer ."); + await copyFile(TEMPLATE_PATH, globalProfile); + console.error(`Created ${globalProfile}`); + console.error( + `Edit that file to describe your role, then run \`${CLI_NAME} pr \` or \`${CLI_NAME} repo\`.` + ); const deviceId = await getDeviceId(); capture("profile_initialized", deviceId, { force, created: true }); } @@ -160,6 +200,10 @@ function repoSlug(identity, repoRoot) { return slugify(String(raw).replace(/\//g, "-")) || "repo"; } +function defaultExplainerDir() { + return process.env.EXPLAINER_DIR || configPaths().globalExplainers; +} + async function appendToIndex(outDir, { filename, title, pr }) { const indexPath = path.join(outDir, "index.md"); if (!existsSync(indexPath)) { @@ -235,7 +279,7 @@ async function explainPR(prRef, flags, profile) { const titleMatch = entry.match(/^#\s+(.+)$/m); const title = titleMatch ? titleMatch[1] : pr.title; - const outDir = process.env.EXPLAINER_DIR || GLOBAL_EXPLAINERS; + const outDir = defaultExplainerDir(); await mkdir(outDir, { recursive: true }); const num = nextEntryNumber(outDir); const filename = `${num}-${slugify(title)}.md`; @@ -318,8 +362,7 @@ async function explainRepo(repoPath, flags, profile) { const titleMatch = entry.match(/^#\s+(.+)$/m); const title = titleMatch ? titleMatch[1] : label; - const baseDir = process.env.EXPLAINER_DIR || GLOBAL_EXPLAINERS; - const outDir = path.join(baseDir, "repos"); + const outDir = path.join(defaultExplainerDir(), "repos"); await mkdir(outDir, { recursive: true }); const num = nextEntryNumber(outDir); const filename = `${num}-${repoSlug(ctx.identity, root)}.md`; @@ -381,7 +424,35 @@ async function main() { return; } - await explainPR(command, flags, profile); + if (command === "pr") { + const prRef = positionals[1]; + if (!prRef) { + console.error(`Missing PR reference.\nRun ${CLI_NAME} --help for usage.`); + process.exitCode = 1; + return; + } + await explainPR(prRef, flags, profile); + return; + } + + // Legacy: `pr-explainer ` without the `pr` subcommand + if (isLegacyBin && looksLikePrRef(command)) { + await explainPR(command, flags, profile); + return; + } + + // Helpful nudge for the new UX + if (looksLikePrRef(command)) { + throw new Error( + `Pass the PR after the \`pr\` subcommand:\n` + + ` ${CLI_NAME} pr ${command}\n\n` + + `Or run \`${CLI_NAME} --help\`.` + ); + } + + throw new Error( + `Unknown command: ${command}\nRun ${CLI_NAME} --help for usage.` + ); } main() diff --git a/src/github.js b/src/github.js index 94585ae..927844e 100644 --- a/src/github.js +++ b/src/github.js @@ -20,8 +20,8 @@ function friendlyGhError(args, err) { `No pull request found for that reference.\n` + `A bare number (e.g. \`42\`) only looks in the repo of your current directory.\n` + `From anywhere, pass a URL or \`owner/repo#42\`:\n` + - ` pr-explainer https://github.com/owner/repo/pull/42\n` + - ` pr-explainer owner/repo#42\n\n` + + ` code-explainer pr https://github.com/owner/repo/pull/42\n` + + ` code-explainer pr owner/repo#42\n\n` + `(${cmd})\n${detail}` ); } @@ -68,7 +68,7 @@ export async function getPR(prRef) { if (!pr.mergedAt) { throw new Error( `PR ${prRef} is not merged yet.\n` + - `pr-explainer only explains merged PRs (past changes that actually shipped).\n` + + `code-explainer pr only explains merged PRs (past changes that actually shipped).\n` + `Pick a merged PR, or wait until this one lands.` ); } diff --git a/src/posthog.js b/src/posthog.js index 06bfd2f..8b1214f 100644 --- a/src/posthog.js +++ b/src/posthog.js @@ -1,8 +1,8 @@ /** - * PostHog analytics client for pr-explainer. + * PostHog analytics client for code-explainer. * - * Uses a persistent anonymous device ID stored in ~/.pr-explainer/device-id - * so returning users are tracked across sessions without collecting any PII. + * Uses a persistent anonymous device ID under ~/.code-explainer (or legacy + * ~/.pr-explainer) so returning users are tracked without collecting PII. * All captures are guarded behind POSTHOG_API_KEY or POSTHOG_PROJECT_TOKEN. */ import { PostHog } from "posthog-node"; @@ -15,7 +15,19 @@ import { loadEnvFiles } from "./load-env.js"; loadEnvFiles(); -const CONFIG_DIR = path.join(os.homedir(), ".pr-explainer"); +const CONFIG_CANDIDATES = [ + path.join(os.homedir(), ".code-explainer"), + path.join(os.homedir(), ".pr-explainer"), +]; + +function resolveConfigDir() { + for (const dir of CONFIG_CANDIDATES) { + if (existsSync(dir)) return dir; + } + return CONFIG_CANDIDATES[0]; +} + +const CONFIG_DIR = resolveConfigDir(); const DEVICE_ID_FILE = path.join(CONFIG_DIR, "device-id"); const AI_TEXT_BUDGET = 80_000; diff --git a/templates/learning-profile.example.md b/templates/learning-profile.example.md index ef9cb7a..47a9250 100644 --- a/templates/learning-profile.example.md +++ b/templates/learning-profile.example.md @@ -1,10 +1,11 @@