prreviewbuddy 0.49.0 → 0.50.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.50.1
+
+**Copy and Ask Buddy look and behave as a pair.** On every issue and question, both icons are the
+same grey at rest and share one soft highlight when you point at them. Copy no longer turns purple on
+hover. Ask Buddy turns purple only while its menu is open. After you copy, the icon turns into a green
+check for a moment and "Copied" appears just below it. It used to appear beside it, on top of Ask
+Buddy. "Copy failed" shows in the same place.
+
+The questions you can ask Buddy AI about a finding or a selection, and the wording that tells Buddy
+which theme a question was asked in, now live in the shared review engine, so the browser extension
+offers the same ones.
+
+In a short window, the list of questions you can ask about a selection now scrolls instead of being
+cut off at the bottom. Escape closes a menu again after the page has redrawn around it.
+
+## 0.50.0
+
+**Every review says which commits it covers.** Beside the branch at the top of a review is its
+commit count. Open it to see where your branch split off from the base, every commit in the review,
+and a reminder that uncommitted changes are never included. A review is always the combined change
+across all of those commits, not just the latest one.
+
+**Help, in the workspace.** A new **Help** place in the sidebar explains what gets reviewed: how
+the base sets the split point, why your local main and origin/main can give different reviews, and
+how to choose between them. The commit count on a review links to it.
+
+**Choosing between local main and origin/main tells you what each would review.** When the two are
+different commits and you have not named a base, PR Review Buddy still asks which one you mean,
+and now lists under each choice how many commits it would review and which ones.
+
+**`prreviewbuddy review --help` works.** It used to say `review` does not take `--help`. Every
+command now prints the help, which has a new section on what gets reviewed, with examples.
+
+## 0.49.2
+
+**Buddy AI remembers which theme you asked in.** Your earlier questions now reach Buddy with the
+theme you had open when you asked them, or a note that they were about the whole change. Asking
+"what is risky here?" in one theme and then "how does that compare?" in another no longer reads to
+Buddy as two questions about the same thing.
+
+## 0.49.1
+
+**Buddy AI says what your question is about.** A line under **Ask Buddy AI** now reads **Asking
+about: the whole change**, or the name of the theme you have open in the Review Path. Buddy always
+sees the whole change; an open theme tells it where to focus, so "what is the risk here?" is
+answered about that theme. The line used to be a small grey label beside the title, cut short, with
+its meaning only in a tooltip. Theme names are now shown in full.
+
 ## 0.49.0
 
 **Change a review from the review itself.** The **⋯** menu at the top of a review now has

package/dist/{delete_review-BBjXPfMV.js → delete_review-BIXqUnpx.js}

@@ -1876,6 +1876,11 @@ var AmbiguousRefError = class extends Error {
 	divergence;
 	/** Whether the name was named by the reviewer or discovered as the default. Changes the wording. */
 	discovered;
+	/**
+	* What a review against each of the two would contain. Absent until `withReviewRanges` adds it,
+	* which needs the head being reviewed and so cannot happen where the name is resolved.
+	*/
+	ranges;
 	constructor(detail) {
 		super(describeAmbiguity(detail));
 		this.name = "AmbiguousRefError";
@@ -1884,9 +1889,49 @@ var AmbiguousRefError = class extends Error {
 		this.remote = detail.remote;
 		if (detail.divergence) this.divergence = detail.divergence;
 		this.discovered = detail.discovered;
+		if (detail.ranges) this.ranges = detail.ranges;
 	}
 };
 /**
+* The same refusal, now saying what choosing each ref would review.
+*
+* Counted from the split point, `git merge-base <ref> <head>`, and not as `<ref>..<head>`: the
+* review diffs from the merge-base, so this has to walk the same boundary or the refusal and the
+* review it leads to could disagree about which commits are in it. Added after resolution because
+* the resolver is shared with the review's own target, which has no head to measure against.
+*/
+async function withReviewRanges(error, repoPath, head) {
+	const [local, remote] = await Promise.all([reviewedCommits(repoPath, error.local.ref, head), reviewedCommits(repoPath, error.remote.ref, head)]);
+	return new AmbiguousRefError({
+		requested: error.requested,
+		local: error.local,
+		remote: error.remote,
+		...error.divergence ? { divergence: error.divergence } : {},
+		discovered: error.discovered,
+		ranges: {
+			...local ? { local } : {},
+			...remote ? { remote } : {}
+		}
+	});
+}
+async function reviewedCommits(repoPath, ref, head) {
+	try {
+		const split = (await git(repoPath, [
+			"merge-base",
+			ref,
+			head
+		])).trim();
+		if (!split) return void 0;
+		return (await git(repoPath, [
+			"rev-list",
+			"--abbrev-commit",
+			`${split}..${head}`
+		])).split("\n").filter(Boolean);
+	} catch {
+		return;
+	}
+}
+/**
 * `refs/heads/feat/foo` and `refs/remotes/origin/feat/foo` are both `feat/foo`.
 *
 * Structural rather than asked of git: the first path segment under `refs/remotes/` is the
@@ -1996,10 +2041,19 @@ function describeAmbiguity(detail) {
 		...refs.map((one) => `  ${one.ref.padEnd(width)}   ${one.sha.slice(0, 7)}`),
 		...detail.divergence ? ["", divergenceLine(name, shorthandOf(detail.remote.ref), detail.divergence)] : [],
 		"",
+		...detail.ranges ? [SPLIT_POINT, ""] : [],
 		"Name the one you mean:",
-		...refs.map((one) => `  prreviewbuddy review --base ${shorthandOf(one.ref)}`)
+		...[[detail.local, detail.ranges?.local], [detail.remote, detail.ranges?.remote]].flatMap(([one, commits]) => [`  prreviewbuddy review --base ${shorthandOf(one.ref)}`, ...commits ? [`      ${rangeLine(commits)}`] : []])
 	].join("\n");
 }
+var SPLIT_POINT = "The base determines the split point. PR Review Buddy reviews the changes on your branch since that point.";
+/** "changes across", because a review is one combined diff and not a review of each commit. */
+function rangeLine(commits) {
+	if (commits.length === 0) return "no commits: nothing on your branch is new against this base";
+	const listed = commits.slice(0, 10).join(" ");
+	const more = commits.length > 10 ? ` and ${commits.length - 10} more` : "";
+	return `changes across ${commits.length} commit${commits.length === 1 ? "" : "s"}: ${listed}${more}`;
+}
 /**
 * How a person spells this ref: the shortest form that still says which one.
 *
@@ -2176,7 +2230,7 @@ async function buildChangeSet(options) {
 	disagreement(files.length, base.display, options.expected);
 	const blobShas = await headBlobShas(repoPath);
 	for (const file of files) file.sha = blobShas.get(file.name) ?? "";
-	const { subjects, authors } = await commitLog(repoPath, base.exact && !await refExists(repoPath, mergeBase) ? "HEAD" : `${mergeBase}..HEAD`);
+	const { subjects, authors, commits } = await commitLog(repoPath, base.exact && !await refExists(repoPath, mergeBase) ? "HEAD" : `${mergeBase}..HEAD`);
 	return {
 		data: {
 			pullRequest: {
@@ -2205,7 +2259,8 @@ async function buildChangeSet(options) {
 		includesUncommitted: false,
 		isLinkedWorktree,
 		checkoutName: basename(repoPath),
-		authors
+		authors,
+		commits
 	};
 }
 /**
@@ -2316,21 +2371,22 @@ async function commitLog(repoPath, range) {
 	const out = await git(repoPath, [
 		"log",
 		"--reverse",
-		"--format=%an%x1f%s",
+		"--format=%H%x1f%an%x1f%s",
 		range
 	]);
 	const subjects = [];
 	const counts = /* @__PURE__ */ new Map();
+	const commits = [];
 	for (const line of out.split("\n")) {
-		const separator = line.indexOf("");
-		if (separator === -1) continue;
-		const name = line.slice(0, separator).trim();
-		const subject = line.slice(separator + 1).trim();
-		if (subject) subjects.push(subject);
-		if (name) counts.set(name, (counts.get(name) ?? 0) + 1);
+		const [sha, name, subject] = line.split("");
+		if (!sha || name === void 0) continue;
+		commits.push(sha.trim());
+		if (subject?.trim()) subjects.push(subject.trim());
+		if (name.trim()) counts.set(name.trim(), (counts.get(name.trim()) ?? 0) + 1);
 	}
 	return {
 		subjects,
+		commits: commits.reverse(),
 		authors: [...counts].map(([name, commits]) => ({
 			name,
 			commits
@@ -2746,8 +2802,14 @@ async function peel(repoPath, named) {
 async function resolveTarget(input) {
 	const root = await repositoryRoot(input.repoPath);
 	if (input.commitRef) return commitTarget(root, input.commitRef);
-	if (input.base) await verifyBase(root, input.base);
-	else await verifyDefaultBase(root);
+	try {
+		if (input.base) await verifyBase(root, input.base);
+		else await verifyDefaultBase(root);
+	} catch (error) {
+		if (!(error instanceof AmbiguousRefError)) throw error;
+		const head = await headToMeasure(root, input);
+		throw head ? await withReviewRanges(error, root, head) : error;
+	}
 	const named = input.base ? { base: input.base } : {};
 	if (input.prUrl) {
 		if (!input.resolveRequest) throw new TargetError(`${input.prUrl} is a pull request, but nothing here can look one up. Check the request out locally and review the branch instead.`);
@@ -2896,6 +2958,23 @@ async function verifyBase(root, base) {
 	throw new TargetError(`There is nothing called \`${base}\` in this repository to compare against. Tried ${candidateRefs(base).map((one) => `\`${one}\``).join(" and ")}. Run \`git fetch\` if it is on the remote and this clone has not seen it yet.`);
 }
 /**
+* The commit the review would be of, as far as it is known before the target is resolved.
+*
+* A pull request's head is not known until the forge is asked, and the refusal exists to come
+* before that, so it gets none and its refusal lists no ranges. A named branch is resolved rather
+* than handed to git as typed, because a name that is itself ambiguous would be settled by git's own
+* preference, which is the guess this module refuses to make.
+*/
+async function headToMeasure(root, input) {
+	if (input.prUrl) return void 0;
+	if (!input.branchRef) return "HEAD";
+	try {
+		return (await resolveBranchRef(root, input.branchRef))?.sha;
+	} catch {
+		return;
+	}
+}
+/**
 * The same check for the base nobody named, which is the one the reported failure came down.
 *
 * A bare `prreviewbuddy review` has no base to verify, so this ran nothing and the refusal landed

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $t as matchingWorkspaceIds, Bn as writeAgentPreference, Bt as progressSteps, Ct as forgeResolver, E as telemetryUploadConsent, Fn as git, Ft as loadJob, Gn as agentById, Gt as followedRefName, Hn as STORE_ROOT, Ht as clearClaim, In as resolveAgent, J as readMarker, Kt as groupByLineage, Ln as resolveModel, Lt as PHASES, Mn as resolveTarget, Nn as displayRef, Ot as checkReview, Pt as isTerminal, Qt as loadWorkspace, S as startJob, T as recordTelemetryUploadConsent, Un as AGENT_IDS, Ut as driverGone, Vn as CONFIG_PATH, Vt as purposeOf, Wn as DEFAULT_AGENT_ID, Wt as isClaimed, X as modelHelpLines, Xt as lineageKeyFor, Y as removeWorktree, Z as relativeTime, _t as MIN_WORKSPACE_PORT, a as wasBlocked, an as reviewedRepositories, b as reanalyseReview, bt as statedWorkspacePort, en as mutateWorkspace, et as queueForReview, ft as BUILD_VERSION, g as runningJobs, gt as MAX_WORKSPACE_PORT, h as liveUpdateFor, ht as DEFAULT_WORKSPACE_PORT, i as liveJobsFor, it as ensureServer, jt as allJobs, l as mergeUpdateInto, lt as stopServer, m as UpdateAlreadyRunningError, n as deleteReview$1, nt as bootstrapUrl, on as summarise, ot as reviewsUrl, pt as PACKAGE_NAME, q as MANAGED_ROOT, qn as detectAgents, rn as recentWorkspaces, tn as positionInLineage, tt as readIndexToken, u as updateReview, ut as workspaceUrl, v as recordKissRun, vt as parseWorkspacePort, w as record$1, x as runJob, xt as writePortPreference, zn as readAgentPreference } from "./delete_review-BBjXPfMV.js";
+import { $t as matchingWorkspaceIds, Bn as writeAgentPreference, Bt as progressSteps, Ct as forgeResolver, E as telemetryUploadConsent, Fn as git, Ft as loadJob, Gn as agentById, Gt as followedRefName, Hn as STORE_ROOT, Ht as clearClaim, In as resolveAgent, J as readMarker, Kt as groupByLineage, Ln as resolveModel, Lt as PHASES, Mn as resolveTarget, Nn as displayRef, Ot as checkReview, Pt as isTerminal, Qt as loadWorkspace, S as startJob, T as recordTelemetryUploadConsent, Un as AGENT_IDS, Ut as driverGone, Vn as CONFIG_PATH, Vt as purposeOf, Wn as DEFAULT_AGENT_ID, Wt as isClaimed, X as modelHelpLines, Xt as lineageKeyFor, Y as removeWorktree, Z as relativeTime, _t as MIN_WORKSPACE_PORT, a as wasBlocked, an as reviewedRepositories, b as reanalyseReview, bt as statedWorkspacePort, en as mutateWorkspace, et as queueForReview, ft as BUILD_VERSION, g as runningJobs, gt as MAX_WORKSPACE_PORT, h as liveUpdateFor, ht as DEFAULT_WORKSPACE_PORT, i as liveJobsFor, it as ensureServer, jt as allJobs, l as mergeUpdateInto, lt as stopServer, m as UpdateAlreadyRunningError, n as deleteReview$1, nt as bootstrapUrl, on as summarise, ot as reviewsUrl, pt as PACKAGE_NAME, q as MANAGED_ROOT, qn as detectAgents, rn as recentWorkspaces, tn as positionInLineage, tt as readIndexToken, u as updateReview, ut as workspaceUrl, v as recordKissRun, vt as parseWorkspacePort, w as record$1, x as runJob, xt as writePortPreference, zn as readAgentPreference } from "./delete_review-BIXqUnpx.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -115,6 +115,7 @@ function parse(argv) {
 		name: "error",
 		message: unknownCommand(head)
 	};
+	if (rest.includes("--help") || rest.includes("-h")) return { name: "help" };
 	const values = {};
 	const flags = /* @__PURE__ */ new Set();
 	const positional = [];
@@ -1064,6 +1065,45 @@ running the same command again carries each one on from where it got to.
 
 Reviews can also be deleted from the list in your browser, one at a time or a whole branch at once.
 
+What gets reviewed
+
+A review is the combined change between a base and the branch you review, as one diff. It is not
+just the latest commit. The base determines the split point (git's merge-base of the base and your
+branch), and PR Review Buddy reviews the changes on your branch since that point.
+
+  main:      A---B---C
+                  \\
+  feature:         D---E
+
+  prreviewbuddy review --base main    reviews D and E together
+
+C is on main but not on your branch, so it is not part of the review, and the review does not show
+its changes as removed. Commits already in the base are never reviewed again.
+
+When your local main and origin/main are different commits, which one you name moves the split
+point:
+
+  origin/main:   A---B
+                      \\
+  local main:          C---D
+                            \\
+  feature:                   E
+
+  --base refs/heads/main      reviews E
+  --base origin/main          reviews C, D and E together
+
+Without --base, the repository's default branch is the base. If its local and remote copies are
+different commits, PR Review Buddy asks which one you mean and says what each would review.
+Uncommitted changes are never included: a review is a fixed snapshot of your commits.
+
+Common examples
+
+  prreviewbuddy review --base refs/heads/main
+                                          everything on this branch since it left your local main
+  prreviewbuddy review --base origin/main
+                                          everything on this branch not yet on origin/main
+  prreviewbuddy review --commit <commit>  one commit, against its parent
+
 There is no account and no API key. PR Review Buddy uses a coding agent installed on your machine
 and that agent's existing authentication, and nothing here ever asks you for a credential.
 

package/dist/server.js

@@ -1,4 +1,4 @@
-import { $ as compactQueue, A as createPrState, An as processDiscussion, At as reviewedShaOf, B as toneOf, Bn as writeAgentPreference, Bt as progressSteps, C as readEvents, Cn as readQueue, D as announceJob, Dn as issuesOutstanding, Dt as checkCodeFreshness, E as telemetryUploadConsent, En as isQuestionOutstanding, Et as fillFileUrlTemplate, F as markAllRead, Fn as git, Ft as loadJob, G as extractJsonText, Gt as followedRefName, H as withUsageRecorded, Hn as STORE_ROOT, I as markRead, It as saveJob, J as readMarker, Jn as AgentCancelledError, Jt as indexReviewGroups, K as ReviewBeingDeletedError, Kn as agentFor, Kt as groupByLineage, L as pruneNotifications, Ln as resolveModel, M as eventName, Mt as endedAt, N as headline, Nt as fail, O as branchOf, On as questionsOutstanding, Ot as checkReview, P as listNotifications, Pn as isCommitReview, Pt as isTerminal, Q as activateQueued, Qt as loadWorkspace, R as readNotification, Rn as clearAgentPreference, Rt as isLiveJob, Sn as queueStamp, St as claimRequestUrl, T as recordTelemetryUploadConsent, Tn as isIssueOutstanding, Tt as remoteHost, U as EXPLAIN_SIMPLY_PROMPT, Un as AGENT_IDS, V as unreadCount$1, Vt as purposeOf, W as asString, Wt as isClaimed, Y as removeWorktree, Yn as AgentUnavailableError, Yt as latestKissRun, Z as relativeTime$1, Zt as lineagePosition, _ as agentEnvOf, _n as parseLifecycle, _t as MIN_WORKSPACE_PORT, a as wasBlocked, at as readServerRecord, bn as queueAddMany, bt as statedWorkspacePort, c as RefreshUnavailableError, cn as workspaceRevision, ct as spawnServer, d as refreshPrContext, dn as activityLabel, dt as writeServerRecord, en as mutateWorkspace, f as isUnchanged, fn as isLifecycle, ft as BUILD_VERSION, gn as offersLifecycle, gt as MAX_WORKSPACE_PORT, h as liveUpdateFor, hn as lifecyclePill, ht as DEFAULT_WORKSPACE_PORT, i as liveJobsFor, in as reviewedCommit, j as createPrUpdate, jn as describeAuthorship, jt as allJobs, k as subjectOf, kn as reviewerDispositions, kt as followedBranch, l as mergeUpdateInto, ln as workspaceStamps, m as UpdateAlreadyRunningError, mn as lifecycleChip, mt as feedbackUrl, n as deleteReview, nn as previousKissResult, o as discardJob, p as askCheckout, pn as lifecycleAction, q as MANAGED_ROOT, qt as indexKeptIds, r as lineageIds, rn as recentWorkspaces, rt as clearServerRecord, s as FETCH_TIMEOUT_MS, sn as touchWorkspace, st as serverEntryExists, t as deleteLineage, tt as readIndexToken, u as updateReview, un as LIFECYCLES, vn as sectionOf, vt as parseWorkspacePort, w as record, wn as doneVerb, wt as forgeFor, x as runJob, xn as queueRemove, xt as writePortPreference, y as startKissJob, yn as queueAdd, yt as resolveWorkspacePort, z as removeNotification, zn as readAgentPreference, zt as phasesFor } from "./delete_review-BBjXPfMV.js";
+import { $ as compactQueue, A as createPrState, An as processDiscussion, At as reviewedShaOf, B as toneOf, Bn as writeAgentPreference, Bt as progressSteps, C as readEvents, Cn as readQueue, D as announceJob, Dn as issuesOutstanding, Dt as checkCodeFreshness, E as telemetryUploadConsent, En as isQuestionOutstanding, Et as fillFileUrlTemplate, F as markAllRead, Fn as git, Ft as loadJob, G as extractJsonText, Gt as followedRefName, H as withUsageRecorded, Hn as STORE_ROOT, I as markRead, It as saveJob, J as readMarker, Jn as AgentCancelledError, Jt as indexReviewGroups, K as ReviewBeingDeletedError, Kn as agentFor, Kt as groupByLineage, L as pruneNotifications, Ln as resolveModel, M as eventName, Mt as endedAt, N as headline, Nt as fail, O as branchOf, On as questionsOutstanding, Ot as checkReview, P as listNotifications, Pn as isCommitReview, Pt as isTerminal, Q as activateQueued, Qt as loadWorkspace, R as readNotification, Rn as clearAgentPreference, Rt as isLiveJob, Sn as queueStamp, St as claimRequestUrl, T as recordTelemetryUploadConsent, Tn as isIssueOutstanding, Tt as remoteHost, U as EXPLAIN_SIMPLY_PROMPT, Un as AGENT_IDS, V as unreadCount$1, Vt as purposeOf, W as asString, Wt as isClaimed, Y as removeWorktree, Yn as AgentUnavailableError, Yt as latestKissRun, Z as relativeTime$1, Zt as lineagePosition, _ as agentEnvOf, _n as parseLifecycle, _t as MIN_WORKSPACE_PORT, a as wasBlocked, at as readServerRecord, bn as queueAddMany, bt as statedWorkspacePort, c as RefreshUnavailableError, cn as workspaceRevision, ct as spawnServer, d as refreshPrContext, dn as activityLabel, dt as writeServerRecord, en as mutateWorkspace, f as isUnchanged, fn as isLifecycle, ft as BUILD_VERSION, gn as offersLifecycle, gt as MAX_WORKSPACE_PORT, h as liveUpdateFor, hn as lifecyclePill, ht as DEFAULT_WORKSPACE_PORT, i as liveJobsFor, in as reviewedCommit, j as createPrUpdate, jn as describeAuthorship, jt as allJobs, k as subjectOf, kn as reviewerDispositions, kt as followedBranch, l as mergeUpdateInto, ln as workspaceStamps, m as UpdateAlreadyRunningError, mn as lifecycleChip, mt as feedbackUrl, n as deleteReview, nn as previousKissResult, o as discardJob, p as askCheckout, pn as lifecycleAction, q as MANAGED_ROOT, qt as indexKeptIds, r as lineageIds, rn as recentWorkspaces, rt as clearServerRecord, s as FETCH_TIMEOUT_MS, sn as touchWorkspace, st as serverEntryExists, t as deleteLineage, tt as readIndexToken, u as updateReview, un as LIFECYCLES, vn as sectionOf, vt as parseWorkspacePort, w as record, wn as doneVerb, wt as forgeFor, x as runJob, xn as queueRemove, xt as writePortPreference, y as startKissJob, yn as queueAdd, yt as resolveWorkspacePort, z as removeNotification, zn as readAgentPreference, zt as phasesFor } from "./delete_review-BIXqUnpx.js";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, timingSafeEqual } from "node:crypto";
@@ -208,6 +208,30 @@ function resolveSectionId(run, sectionId) {
 	return run.result.sections.some((section) => section.id === sectionId) ? namespaced(run.id, sectionId) : sectionId;
 }
 //#endregion
+//#region ../../packages/review-harness/src/domain/ai_review/ask_scope.ts
+/**
+* Where an earlier question was asked, which the question alone does not say.
+*
+* "What is risky here?" in one theme followed by "and how does that compare?" in another reads, as
+* bare text, as two questions about the same thing. `undefined` is a question recorded before
+* scopes were, and gets no label: calling it "the whole change" would state something nobody
+* recorded. A theme that has since gone, because the review was updated, is said to have gone.
+*/
+function askedWhere(sections, sectionId) {
+	if (sectionId === void 0) return null;
+	if (sectionId === null) return "(asked about the whole change)";
+	const section = sections.find((s) => s.id === sectionId);
+	return section ? `(asked while reading the "${section.title}" theme)` : "(asked while reading a theme that is no longer in the review)";
+}
+/**
+* The theme the reviewer has open, named rather than used to filter what the model sees: they
+* routinely ask "does this interact with X", where X is in another theme.
+*/
+function readingThemeLine(sections, sectionId) {
+	const section = sectionId === null ? void 0 : sections.find((s) => s.id === sectionId);
+	return section ? `The reviewer is currently reading the "${section.title}" theme. Answer with that in view, but do not ignore the rest of the change if it bears on the question.` : null;
+}
+//#endregion
 //#region ../../packages/review-harness/src/domain/utils/html.ts
 function escapeHtml$1(value) {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -371,6 +395,7 @@ var PATHS = {
 	reviews: "<path d=\"M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01\"/>",
 	notifications: "<path d=\"M18 8a6 6 0 0 0-12 0c0 7-3 9-3 9h18s-3-2-3-9\"/><path d=\"M13.7 21a2 2 0 0 1-3.4 0\"/>",
 	settings: "<circle cx=\"12\" cy=\"12\" r=\"3\"/><path d=\"M19.4 15a1.7 1.7 0 0 0 .3 1.8l.1.1a2 2 0 1 1-2.8 2.8l-.1-.1a1.7 1.7 0 0 0-1.8-.3 1.7 1.7 0 0 0-1 1.5V21a2 2 0 1 1-4 0v-.1a1.7 1.7 0 0 0-1.1-1.5 1.7 1.7 0 0 0-1.8.3l-.1.1a2 2 0 1 1-2.8-2.8l.1-.1a1.7 1.7 0 0 0 .3-1.8 1.7 1.7 0 0 0-1.5-1H3a2 2 0 1 1 0-4h.1a1.7 1.7 0 0 0 1.5-1.1 1.7 1.7 0 0 0-.3-1.8l-.1-.1a2 2 0 1 1 2.8-2.8l.1.1a1.7 1.7 0 0 0 1.8.3H9a1.7 1.7 0 0 0 1-1.5V3a2 2 0 1 1 4 0v.1a1.7 1.7 0 0 0 1 1.5 1.7 1.7 0 0 0 1.8-.3l.1-.1a2 2 0 1 1 2.8 2.8l-.1.1a1.7 1.7 0 0 0-.3 1.8V9a1.7 1.7 0 0 0 1.5 1H21a2 2 0 1 1 0 4h-.1a1.7 1.7 0 0 0-1.5 1z\"/>",
+	help: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M9.1 9a3 3 0 0 1 5.8 1c0 2-3 3-3 3\"/><path d=\"M12 17h.01\"/>",
 	feedback: "<path d=\"m22 2-7 20-4-9-9-4z\"/><path d=\"M22 2 11 13\"/>",
 	stop: "<path d=\"M12 2v10\"/><path d=\"M18.4 6.6a9 9 0 1 1-12.8 0\"/>",
 	restart: "<path d=\"M21 12a9 9 0 1 1-2.64-6.36\"/><path d=\"M21 3v6h-6\"/>"
@@ -444,6 +469,12 @@ var WORKSPACE_PLACES = [
 		href: "/settings",
 		icon: "settings",
 		label: "Settings"
+	},
+	{
+		place: "help",
+		href: "/help",
+		icon: "help",
+		label: "Help"
 	}
 ];
 /**
@@ -766,9 +797,10 @@ var FINDING_COPY_CLASS = "pr-helper-finding-copy";
 * buttons, where an icon alone read as decoration. In the heading it is on its own, and a word
 * would give a utility the weight of the title beside it. What it does is said by a hover
 * tooltip (`data-tip`, the same CSS tooltip the pills use, not a native `title`) and by its
-* accessible name. "Copied" and "Copy failed" still show as words, because a picture cannot say
-* that the click did something. The resting name is kept on the button so the reset returns to
-* "Copy finding" rather than to a chat reply's "Copy message".
+* accessible name. After a click it shows a green check and says "Copied" (or "Copy failed") in
+* the bubble below it, the words used everywhere else, but not inline: beside it is Ask Buddy. The
+* resting name and tip are kept on the button so the reset returns to "Copy finding" rather than to
+* a chat reply's "Copy message".
 */
 function renderFindingCopySource(source, kind) {
 	const name = kind === "issue" ? "Copy finding" : "Copy question";
@@ -781,11 +813,12 @@ function renderFindingCopySource(source, kind) {
 /** Where a finding's button keeps its resting word and name. Absent on a chat reply's. */
 var IDLE_LABEL_ATTR = "data-copy-idle-label";
 var IDLE_ARIA_ATTR = "data-copy-idle-aria";
+var IDLE_TIP_ATTR = "data-copy-idle-tip";
 function button(handle, idle) {
 	const { icon } = STATES$1.idle;
 	const label = idle?.label ?? STATES$1.idle.label;
 	const aria = idle?.aria ?? STATES$1.idle.aria;
-	const remembered = idle ? ` ${IDLE_LABEL_ATTR}="${escapeHtml$1(label)}" ${IDLE_ARIA_ATTR}="${escapeHtml$1(aria)}"` : "";
+	const remembered = idle ? ` ${IDLE_LABEL_ATTR}="${escapeHtml$1(label)}" ${IDLE_ARIA_ATTR}="${escapeHtml$1(aria)}" ${IDLE_TIP_ATTR}="${escapeHtml$1(idle.tip)}"` : "";
 	const control = `<button type="button" class="${idle ? `${MESSAGE_COPY_CLASS} ${FINDING_COPY_CLASS}` : MESSAGE_COPY_CLASS}" ${handle}${remembered}${idle ? ` data-tip="${escapeHtml$1(idle.tip)}"` : ""} aria-label="${escapeHtml$1(aria)}"><span class="${MESSAGE_COPY_CLASS}-icon" aria-hidden="true">${svg(icon)}</span><span class="${MESSAGE_COPY_CLASS}-label"${label ? "" : " hidden"}>${escapeHtml$1(label)}</span></button>`;
 	return idle ? control : `<div class="${MESSAGE_ACTIONS_CLASS}">${control}</div>`;
 }
@@ -806,8 +839,7 @@ function svg(paths) {
 * closes and positions exactly as that one does. The panel is empty here and filled when it opens,
 * because it lists the reviewer's saved prompts and those change without the page re-rendering.
 *
-* Workspace only. The extension renders these cards too, and there is no Buddy pane behind a card
-* there for this to open, so `ReviewTabOptions.askBuddy` gates it and the extension never sets it.
+* The host decides where the answer appears; `ReviewTabOptions.askBuddy` says the host has wired it.
 */
 var ASK_BUDDY_LABEL = "Ask Buddy";
 /** Four-point sparkle, the conventional mark for "ask the AI". currentColor, like Copy beside it. */
@@ -5011,6 +5043,43 @@ function renderSubject(changeSet) {
     <span>${against}</span>`;
 }
 /**
+* Which commits this review is of, opened from the bar beside what it compares.
+*
+* Beside `.prb-change-ref` rather than inside it, because that element clips to keep the bar one
+* line and a panel inside it would be cut off. The pill's own label is a fact (how many commits),
+* so the bar gains information even closed. Facts only, and about this review: the general
+* explanation is the Help page's, linked when there is a server to answer the link.
+*
+* The count comes from the stored commit list, or from the authors' counts for a review made before
+* the list was recorded, which then says how many without listing them. Neither: no count at all,
+* never a zero.
+*/
+function renderRange(changeSet, live) {
+	const commits = changeSet.commits;
+	const count = commits?.length ?? changeSet.authors?.reduce((sum, author) => sum + author.commits, 0);
+	const counted = count !== void 0 && count > 0 ? count : void 0;
+	const plural = (n) => `${n} commit${n === 1 ? "" : "s"}`;
+	const sha = (value) => `<code>${escapeHtml$1(value.slice(0, 7))}</code>`;
+	const lines = [];
+	if (changeSet.targetType === "commit") {
+		const parent = changeSet.parentSha;
+		const against = !parent ? "the empty tree" : `its ${(changeSet.parentCount ?? 1) > 1 ? "first parent" : "parent"} ${sha(parent)}`;
+		lines.push(`The change commit ${sha(changeSet.data.pullRequest.head.sha)} made, compared against ${against}.`);
+	} else {
+		lines.push(changeSet.mergeBase ? `Compared against <code>${escapeHtml$1(changeSet.baseRef)}</code>, from where this branch split off at ${sha(changeSet.mergeBase)}.` : `Compared against <code>${escapeHtml$1(changeSet.baseRef)}</code>.`);
+		if (commits && commits.length > 0) {
+			const more = commits.length > 10 ? ` and ${commits.length - 10} more` : "";
+			lines.push(`Changes across ${plural(commits.length)}: ${commits.slice(0, 10).map(sha).join(" ")}${more}.`);
+		} else if (counted) lines.push(`Changes across ${plural(counted)}.`);
+	}
+	lines.push(changeSet.includesUncommitted ? "This review also read uncommitted changes in the working tree." : "Uncommitted changes are never part of a review.");
+	if (live) lines.push("<a href=\"/help#what-gets-reviewed\">How review ranges work</a>");
+	return `<details class="prb-range" data-range-details>
+    <summary class="prb-range-summary">${changeSet.targetType === "commit" ? "1 commit" : counted ? plural(counted) : "Range"}</summary>
+    <div class="prb-range-panel">${lines.map((line) => `<p>${line}</p>`).join("")}</div>
+  </details>`;
+}
+/**
 * The review's own bar, below the global strip.
 *
 * Everything here is about this review and nothing else is: the strip above carries the workspace's
@@ -5031,6 +5100,7 @@ function renderReviewBar(view, freshness) {
     ${changeSet.includesUncommitted ? "<span class=\"prb-file-status\">+ working tree</span>" : ""}
     ${renderAuthor(view)}
   </span>
+  ${renderRange(changeSet, Boolean(view.token))}
   <div class="prb-header-stats">
     <span>${fileCount} file${fileCount === 1 ? "" : "s"}</span>
     <span><span class="prb-add">+${additions}</span> <span class="prb-del">&minus;${deletions}</span></span>
@@ -5635,8 +5705,10 @@ function renderAsk(view, sections, paused = false) {
     tabindex="0"
   ></div>
   <div class="prb-ask-header">
-    <h2>Ask Buddy AI</h2>
-    <span class="prb-ask-scope" data-ask-scope>whole change</span>
+    <hgroup class="prb-ask-heading">
+      <h2>Ask Buddy AI</h2>
+      <p class="prb-ask-scope">Asking about: <span data-ask-scope>the whole change</span></p>
+    </hgroup>
     ${renderFocusToggle("buddy", "Buddy AI")}
     <button type="button" class="prb-ask-hide" data-ask-toggle aria-controls="prb-ask" aria-label="Hide Buddy AI">${ASK_HIDE_ICON}</button>
   </div>
@@ -7900,6 +7972,87 @@ function defaultFetchDeps() {
 	};
 }
 //#endregion
+//#region ../../packages/review-harness/src/workspace/help_page.ts
+/** The diagrams are text on purpose: they are the same ones `prreviewbuddy --help` prints. */
+var TOPICS = [{
+	id: "what-gets-reviewed",
+	title: "What gets reviewed",
+	body: `<p>A review is the combined change between a base and the branch you review, shown as one
+    diff. It is not just the latest commit. The base determines the split point: the commit where
+    your branch left it (git calls this the merge-base). PR Review Buddy reviews the changes on your
+    branch since that point.</p>
+<pre class="prb-help-diagram">main:      A---B---C
+                \\
+feature:         D---E</pre>
+    <p>Reviewing <code>feature</code> against <code>main</code> covers D and E together. C is on
+    main but not on your branch, so it is not part of the review, and the review does not show its
+    changes as removed. Commits already in the base are never reviewed again.</p>
+
+    <h3>Local main and origin/main</h3>
+    <p>Your local <code>main</code> can hold commits that are not on <code>origin/main</code> yet,
+    such as a merge you have not pushed. When the two are different commits, the one you choose
+    moves the split point.</p>
+<pre class="prb-help-diagram">origin/main:   A---B
+                    \\
+local main:          C---D
+                          \\
+feature:                   E</pre>
+    <ul>
+      <li>Against local <code>main</code>, the review covers E.</li>
+      <li>Against <code>origin/main</code>, it covers C, D and E together.</li>
+    </ul>
+    <p>When nobody names a base and the two differ, PR Review Buddy does not guess. It asks which
+    one you mean and says which commits each would review.</p>
+
+    <h3>Uncommitted changes</h3>
+    <p>Never included. A review is a fixed snapshot of your commits, made in a checkout of its own,
+    so work you have not committed is not part of it.</p>
+
+    <h3>Choosing a base</h3>
+    <p>The base is chosen when the review is made, in the terminal:</p>
+    <ul>
+      <li><code>prreviewbuddy review --base refs/heads/main</code> for everything on your branch since it left your local main</li>
+      <li><code>prreviewbuddy review --base origin/main</code> for everything on your branch not yet on origin/main</li>
+      <li><code>prreviewbuddy review --commit &lt;commit&gt;</code> for one commit, against its parent</li>
+    </ul>
+    <p>Every review shows its own range. The commit count beside the branch name at the top of a
+    review opens its split point and the commits it covers.</p>`
+}];
+function renderHelpPage(view) {
+	return `<!doctype html>
+<html lang="en"${themeAttribute(view.theme)}>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Help · PR Review Buddy</title>
+<link rel="icon" type="image/png" href="/assets/icon128.png">
+<link rel="stylesheet" href="/assets/sidebar.css">
+<link rel="stylesheet" href="/assets/shell.css">
+</head>
+<body class="prb-index-body" data-way-back="${escapeHtml$1(wayBackSentence())}">
+${renderGlobalBar({
+		current: "help",
+		unread: view.unreadNotifications ?? 0,
+		driving: view.driving
+	})}
+${renderContextBar("Help", "")}
+<div class="prb-shell">
+${renderWorkspaceRail({
+		current: "help",
+		unread: view.unreadNotifications ?? 0
+	})}
+<main class="prb-index prb-help">
+  ${TOPICS.map((topic) => `<section class="prb-help-topic" id="${topic.id}">
+    <h2>${escapeHtml$1(topic.title)}</h2>
+    ${topic.body}
+  </section>`).join("")}
+</main>
+</div>
+<script src="/assets/help.js" type="module"><\/script>
+</body>
+</html>`;
+}
+//#endregion
 //#region ../../packages/review-harness/src/workspace/notifications_page.ts
 function renderNotificationsPage(view) {
 	const unread = view.notifications.filter((notification) => notification.readAt === void 0).length;
@@ -8234,7 +8387,8 @@ function extractAnswer(raw) {
 * and wrongly.
 */
 function buildPrompt$2(workspace, question, sectionId, cwd) {
-	const section = workspace.session.result?.sections.find((s) => s.id === sectionId);
+	const sections = workspace.session.result?.sections ?? [];
+	const reading = readingThemeLine(sections, sectionId);
 	const recent = workspace.transcript.slice(-4);
 	return [
 		SYSTEM_PROMPT$1,
@@ -8246,11 +8400,14 @@ function buildPrompt$2(workspace, question, sectionId, cwd) {
 		"---",
 		"DIFF:",
 		workspace.diff,
-		...section ? ["---", `The reviewer is currently reading the "${section.title}" theme. Answer with that in view, but do not ignore the rest of the change if it bears on the question.`] : [],
+		...reading ? ["---", reading] : [],
 		...recent.length > 0 ? [
 			"---",
 			"EARLIER IN THIS CONVERSATION:",
-			recent.map((entry) => `Q: ${entry.question}\nA: ${entry.answer}`).join("\n\n")
+			recent.map((entry) => {
+				const where = askedWhere(sections, entry.sectionId);
+				return `Q${where ? ` ${where}` : ""}: ${entry.question}\nA: ${entry.answer}`;
+			}).join("\n\n")
 		] : [],
 		"---",
 		`QUESTION: ${question}`
@@ -9263,6 +9420,7 @@ async function handle(req, res, options) {
 	if (url.pathname === "/open") return handleOpen(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/settings") return void handleSettings(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/notifications") return void handleNotifications(req, res, url.searchParams, options.indexToken);
+	if (url.pathname === "/help") return void handleHelp(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/notifications/open") return handleNotificationOpen(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/notifications/recent") return handleRecentNotifications(req, res, url.searchParams, options.indexToken);
 	if (url.pathname === "/pin") return handlePin(req, res, options.indexToken);
@@ -9472,6 +9630,18 @@ async function handleSettings(req, res, params, indexToken) {
 	}), indexCookieHeader(indexToken));
 }
 /**
+* Help. Static, but still behind the index's credential like every other workspace place: its
+* rail and strip carry the unread count, which is this machine's state.
+*/
+function handleHelp(req, res, params, indexToken) {
+	if (!indexAuthorised(req, params, indexToken)) return refuseIndex(req, res);
+	sendHtml(res, 200, renderHelpPage({
+		unreadNotifications: unreadCount$1(),
+		driving: isDriving(),
+		theme: readPreferences().theme
+	}), indexCookieHeader(indexToken));
+}
+/**
 * Whether the caller is a browser navigating, rather than something reading the API.
 *
 * `Accept` is the only signal available and browsers are consistent about it: a navigation asks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prreviewbuddy",
-  "version": "0.49.0",
+  "version": "0.50.1",
   "description": "Review a branch or pull request in an isolated checkout, from your terminal, with the coding agent you already have installed.",
   "license": "UNLICENSED",
   "homepage": "https://prreviewbuddy.com",

package/static/help.js

@@ -0,0 +1 @@
+import{c as e,t}from"./chunk-BeL0x-wt.js";t(`/restart`),e(window,()=>window.location.reload());