prreviewbuddy 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 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
+everything the card's menu on the reviews list has: **Mark reviewed** or **Mark in progress**,
+**Mark waiting**, **Mark done**, **Move to active**, and **Add to review queue** or **Remove from
+review queue**, as well as Save, Copy review ID and Delete. You no longer have to go back to the
+list to park or queue the review you are reading. Waiting, Done and the queue belong to the branch,
+so they are offered on its newest review; an older review of the same branch points you to it.
+
+**The top bar says where the review stands.** It shows the files, the size of the change, whether
+the review is up to date, and two labels: **Reviewed** or **In progress**, and **Waiting** or
+**Done** when the review is parked. None of them are buttons. **Check for updates** has moved into
+the **⋯** menu, because the page already checks by itself every minute while you are looking at it
+and whenever you come back to the tab. Its answer, such as "No change", appears where the review's
+freshness is shown.
+
+**Check for updates works more than once.** After one check it stayed greyed out until you reloaded
+the page. It now becomes available again as soon as the check finishes, and pressing it while the
+page is checking by itself no longer does nothing: it waits for that check and then runs its own.
+
+**The review page keeps up while it is open.** If a Waiting review's branch gets new commits while
+you are looking at it, the page now says **Changed while waiting** within a minute, without a
+reload, and offers **Mark waiting** again. Changes made from the reviews list in another tab show
+up the same way. Adding a review to a full review queue from its page now says the queue is full
+instead of appearing to work.
+
+**Reviewed reviews stay in your queue.** Marking a review **Reviewed** no longer takes it out of
+the review queue, from the reviews list or from the review itself. Reviewed records that you have
+been through it, not that you are finished with it; **Waiting** and **Done** are how you say that,
+and they still take a review out of the queue. `prreviewbuddy review --queue` now queues a Reviewed
+review instead of refusing it, and, like adding from the workspace, moves a Waiting or Done review
+back to Active when it goes in.
+
+**Buddy AI has its own tab.** It is no longer a button in the top bar. When Buddy AI's panel is
+closed, a **Buddy AI** tab sits on the right edge of the window; press it to open the panel. The
+double arrow in the panel's header closes it.
+
 ## 0.48.0
 
 **Active, Waiting and Done.** A review can now be marked **Waiting**, for when you have done your

package/dist/{delete_review-D52wkt66.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
@@ -4089,19 +4168,6 @@ function queueRemove(id) {
 	return updateQueue((current) => current.includes(id) ? current.filter((queued) => queued !== id) : null);
 }
 /**
-* The invariant, as one named thing: the queue holds unfinished work only.
-*
-* Removing on completion is half of it. The other half is that this **does nothing** when
-* `complete` is false, and that half only exists as a written rule -- there is no line of code for
-* it to be visible in. Re-adding there would make membership something inferred from status rather
-* than chosen, so a reviewer who took a review out of the queue and later moved it back to In
-* progress would find it queued again with no idea why.
-*/
-function dequeueOnComplete(id, complete) {
-	if (!complete) return;
-	queueRemove(id);
-}
-/**
 * A token for the index's revision, equality only.
 *
 * The queue changes only when a person deliberately changes it, so unlike a running job's progress
@@ -4143,14 +4209,17 @@ function normalise(ids) {
 var LIFECYCLES = [
 	{
 		id: "active",
+		name: "Active",
 		action: "Move to active"
 	},
 	{
 		id: "waiting",
+		name: "Waiting",
 		action: "Mark waiting"
 	},
 	{
 		id: "done",
+		name: "Done",
 		action: "Mark done"
 	}
 ];
@@ -4170,6 +4239,23 @@ function parseLifecycle(raw) {
 function lifecycleAction(lifecycle) {
 	return LIFECYCLES.find((entry) => entry.id === lifecycle).action;
 }
+/**
+* The review page's lifecycle pill, or absent for Active, which says nothing (as an open pull
+* request says nothing). A parked review that has changed since reads as the card's chip does, so
+* the page and the list give one answer about the same review.
+*/
+function lifecyclePill(lifecycle, activity) {
+	if (!lifecycle) return void 0;
+	const chip = lifecycleChip(lifecycle, activity);
+	if (chip !== void 0) return {
+		text: chip,
+		changed: true
+	};
+	return {
+		text: LIFECYCLES.find((entry) => entry.id === lifecycle.state).name,
+		changed: false
+	};
+}
 var ACTIVITY_LABELS = {
 	created: "Created",
 	updated: "Updated",
@@ -4658,9 +4744,8 @@ function groupByLineage(reviews) {
 * on an old review is "then what is the current one", and answering it by sending them to the
 * index costs them the page they were reading. See `RelatedReview` for what may travel and why.
 */
-function lineagePosition(workspace) {
+function lineagePosition(workspace, all = recentWorkspaces(Number.MAX_SAFE_INTEGER)) {
 	const review = summarise(workspace);
-	const all = recentWorkspaces(Number.MAX_SAFE_INTEGER);
 	return {
 		...positionInLineage(review, all),
 		reviews: relatedReviews(review, all)
@@ -7650,9 +7735,10 @@ function compactQueue(stored) {
 /**
 * Put one review on the queue, the way the index's Add does, and say how that went.
 *
-* **A completed review is left out**, not queued and not reopened. The queue holds unfinished work
-* only -- `dequeueOnComplete` is the other half of that rule -- and quietly moving somebody's review
-* back to In progress because a command mentioned it is a status change nobody asked for.
+* **A Reviewed review is queued like any other.** Reviewed says what the reviewer has done with it,
+* not that the work is over; that is Done. A Waiting or Done review that goes in is put back in
+* Active, as it is from the page (`activateQueued`), because asking for it in the queue is asking
+* to work on it again.
 *
 * Already queued is `already`, not a move: the same rule `queueAdd` keeps, for the same reason.
 *
@@ -7660,11 +7746,9 @@ function compactQueue(stored) {
 * was queued would otherwise hold a place, and a live review could be refused as "full" by it.
 */
 function queueForReview(id) {
-	const workspace = loadWorkspace(id);
-	if (!workspace) return "gone";
-	if (workspace.completedAt !== void 0) return "complete";
+	if (!loadWorkspace(id)) return "gone";
 	let result = "added";
-	return updateQueue((current) => {
+	const stored = updateQueue((current) => {
 		const live = current.filter(isLive);
 		const unchanged = live.length === current.length ? null : live;
 		if (live.includes(id)) {
@@ -7676,7 +7760,29 @@ function queueForReview(id) {
 			return unchanged;
 		}
 		return [...live, id];
-	}) === null ? "unsaved" : result;
+	});
+	if (stored === null) return "unsaved";
+	if (result === "added") activateQueued([id], stored);
+	return result;
+}
+/**
+* Queueing a review puts it back in Active.
+*
+* The queue is work the reviewer wants surfaced next, and Waiting and Done both say the opposite; a
+* queued review folded away in Done would be a contradiction the page then has to draw. Parking
+* takes a review out of the queue, and this is the same rule read the other way. Only what actually
+* went in: a review refused because the queue was full keeps the lifecycle it had.
+*
+* Every way in calls this: a card, the bulk bar, the review's own page and `--queue`.
+*/
+function activateQueued(ids, queue) {
+	const queued = new Set(queue);
+	for (const one of ids) {
+		if (!queued.has(one) || loadWorkspace(one)?.lifecycle === void 0) continue;
+		mutateWorkspace(one, (current) => {
+			current.lifecycle = void 0;
+		});
+	}
 }
 function isLive(id) {
 	return loadWorkspace(id) !== null;
@@ -12775,4 +12881,4 @@ function lineageIds(id) {
 	return [.../* @__PURE__ */ new Set([id, ...lineage.map((review) => review.id)])];
 }
 //#endregion
-export { queueForReview as $, mutateWorkspace as $t, createPrState as A, describeAuthorship as An, allJobs as At, toneOf as B, CONFIG_PATH as Bn, purposeOf as Bt, readEvents as C, doneVerb as Cn, forgeFor as Ct, announceJob as D, questionsOutstanding as Dn, checkReview as Dt, telemetryUploadConsent as E, issuesOutstanding as En, checkCodeFreshness as Et, markAllRead as F, resolveAgent as Fn, saveJob as Ft, extractJsonText as G, agentFor as Gn, groupByLineage as Gt, withUsageRecorded as H, AGENT_IDS as Hn, driverGone as Ht, markRead as I, resolveModel as In, PHASES as It, readMarker as J, AgentUnavailableError as Jn, latestKissRun as Jt, ReviewBeingDeletedError as K, detectAgents as Kn, indexKeptIds as Kt, pruneNotifications as L, clearAgentPreference as Ln, isLiveJob as Lt, eventName as M, displayRef as Mn, fail as Mt, headline as N, isCommitReview as Nn, isTerminal as Nt, branchOf as O, reviewerDispositions as On, followedBranch as Ot, listNotifications as P, git as Pn, loadJob as Pt, compactQueue as Q, matchingWorkspaceIds as Qt, readNotification as R, readAgentPreference as Rn, phasesFor as Rt, startJob as S, readQueue as Sn, forgeResolver as St, recordTelemetryUploadConsent as T, isQuestionOutstanding as Tn, fillFileUrlTemplate as Tt, EXPLAIN_SIMPLY_PROMPT as U, DEFAULT_AGENT_ID as Un, isClaimed as Ut, unreadCount as V, STORE_ROOT as Vn, clearClaim as Vt, asString as W, agentById as Wn, followedRefName as Wt, modelHelpLines as X, lineagePosition as Xt, removeWorktree as Y, lineageKeyFor as Yt, relativeTime as Z, loadWorkspace as Zt, agentEnvOf as _, dequeueOnComplete as _n, parseWorkspacePort as _t, wasBlocked as a, summarise as an, reviewsUrl as at, reanalyseReview as b, queueRemove as bn, writePortPreference as bt, RefreshUnavailableError as c, workspaceStamps as cn, stopServer as ct, refreshPrContext as d, isLifecycle as dn, BUILD_VERSION as dt, positionInLineage as en, readIndexToken as et, isUnchanged as f, lifecycleAction as fn, PACKAGE_NAME as ft, runningJobs as g, sectionOf as gn, MIN_WORKSPACE_PORT as gt, liveUpdateFor as h, parseLifecycle as hn, MAX_WORKSPACE_PORT as ht, liveJobsFor as i, reviewedRepositories as in, readServerRecord as it, createPrUpdate as j, resolveTarget as jn, endedAt as jt, subjectOf as k, processDiscussion as kn, reviewedShaOf as kt, mergeUpdateInto as l, LIFECYCLES as ln, workspaceUrl as lt, UpdateAlreadyRunningError as m, offersLifecycle as mn, DEFAULT_WORKSPACE_PORT as mt, deleteReview as n, recentWorkspaces as nn, clearServerRecord as nt, discardJob as o, touchWorkspace as on, serverEntryExists as ot, askCheckout as p, lifecycleChip as pn, feedbackUrl as pt, MANAGED_ROOT as q, AgentCancelledError as qn, indexReviewGroups as qt, lineageIds as r, reviewedCommit as rn, ensureServer as rt, FETCH_TIMEOUT_MS as s, workspaceRevision as sn, spawnServer as st, deleteLineage as t, previousKissResult as tn, bootstrapUrl as tt, updateReview as u, activityLabel as un, writeServerRecord as ut, recordKissRun as v, queueAdd as vn, resolveWorkspacePort as vt, record as w, isIssueOutstanding as wn, remoteHost as wt, runJob as x, queueStamp as xn, claimRequestUrl as xt, startKissJob as y, queueAddMany as yn, statedWorkspacePort as yt, removeNotification as z, writeAgentPreference as zn, progressSteps as zt };
+export { compactQueue as $, matchingWorkspaceIds as $t, createPrState as A, processDiscussion as An, reviewedShaOf as At, toneOf as B, writeAgentPreference as Bn, progressSteps as Bt, readEvents as C, readQueue as Cn, forgeResolver as Ct, announceJob as D, issuesOutstanding as Dn, checkCodeFreshness as Dt, telemetryUploadConsent as E, isQuestionOutstanding as En, fillFileUrlTemplate as Et, markAllRead as F, git as Fn, loadJob as Ft, extractJsonText as G, agentById as Gn, followedRefName as Gt, withUsageRecorded as H, STORE_ROOT as Hn, clearClaim as Ht, markRead as I, resolveAgent as In, saveJob as It, readMarker as J, AgentCancelledError as Jn, indexReviewGroups as Jt, ReviewBeingDeletedError as K, agentFor as Kn, groupByLineage as Kt, pruneNotifications as L, resolveModel as Ln, PHASES as Lt, eventName as M, resolveTarget as Mn, endedAt as Mt, headline as N, displayRef as Nn, fail as Nt, branchOf as O, questionsOutstanding as On, checkReview as Ot, listNotifications as P, isCommitReview as Pn, isTerminal as Pt, activateQueued as Q, loadWorkspace as Qt, readNotification as R, clearAgentPreference as Rn, isLiveJob as Rt, startJob as S, queueStamp as Sn, claimRequestUrl as St, recordTelemetryUploadConsent as T, isIssueOutstanding as Tn, remoteHost as Tt, EXPLAIN_SIMPLY_PROMPT as U, AGENT_IDS as Un, driverGone as Ut, unreadCount as V, CONFIG_PATH as Vn, purposeOf as Vt, asString as W, DEFAULT_AGENT_ID as Wn, isClaimed as Wt, modelHelpLines as X, lineageKeyFor as Xt, removeWorktree as Y, AgentUnavailableError as Yn, latestKissRun as Yt, relativeTime as Z, lineagePosition as Zt, agentEnvOf as _, parseLifecycle as _n, MIN_WORKSPACE_PORT as _t, wasBlocked as a, reviewedRepositories as an, readServerRecord as at, reanalyseReview as b, queueAddMany as bn, statedWorkspacePort as bt, RefreshUnavailableError as c, workspaceRevision as cn, spawnServer as ct, refreshPrContext as d, activityLabel as dn, writeServerRecord as dt, mutateWorkspace as en, queueForReview as et, isUnchanged as f, isLifecycle as fn, BUILD_VERSION as ft, runningJobs as g, offersLifecycle as gn, MAX_WORKSPACE_PORT as gt, liveUpdateFor as h, lifecyclePill as hn, DEFAULT_WORKSPACE_PORT as ht, liveJobsFor as i, reviewedCommit as in, ensureServer as it, createPrUpdate as j, describeAuthorship as jn, allJobs as jt, subjectOf as k, reviewerDispositions as kn, followedBranch as kt, mergeUpdateInto as l, workspaceStamps as ln, stopServer as lt, UpdateAlreadyRunningError as m, lifecycleChip as mn, feedbackUrl as mt, deleteReview as n, previousKissResult as nn, bootstrapUrl as nt, discardJob as o, summarise as on, reviewsUrl as ot, askCheckout as p, lifecycleAction as pn, PACKAGE_NAME as pt, MANAGED_ROOT as q, detectAgents as qn, indexKeptIds as qt, lineageIds as r, recentWorkspaces as rn, clearServerRecord as rt, FETCH_TIMEOUT_MS as s, touchWorkspace as sn, serverEntryExists as st, deleteLineage as t, positionInLineage as tn, readIndexToken as tt, updateReview as u, LIFECYCLES as un, workspaceUrl as ut, recordKissRun as v, sectionOf as vn, parseWorkspacePort as vt, record as w, doneVerb as wn, forgeFor as wt, runJob as x, queueRemove as xn, writePortPreference as xt, startKissJob as y, queueAdd as yn, resolveWorkspacePort as yt, removeNotification as z, readAgentPreference as zn, phasesFor as zt };

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as queueForReview, $t as mutateWorkspace, At as allJobs, Bn as CONFIG_PATH, Bt as purposeOf, Dt as checkReview, E as telemetryUploadConsent, Fn as resolveAgent, Gt as groupByLineage, Hn as AGENT_IDS, Ht as driverGone, In as resolveModel, It as PHASES, J as readMarker, Kn as detectAgents, Mn as displayRef, Nt as isTerminal, Pn as git, Pt as loadJob, Qt as matchingWorkspaceIds, Rn as readAgentPreference, S as startJob, St as forgeResolver, T as recordTelemetryUploadConsent, Un as DEFAULT_AGENT_ID, Ut as isClaimed, Vn as STORE_ROOT, Vt as clearClaim, Wn as agentById, Wt as followedRefName, X as modelHelpLines, Y as removeWorktree, Yt as lineageKeyFor, Z as relativeTime, Zt as loadWorkspace, _t as parseWorkspacePort, a as wasBlocked, an as summarise, at as reviewsUrl, b as reanalyseReview, bt as writePortPreference, ct as stopServer, dt as BUILD_VERSION, en as positionInLineage, et as readIndexToken, ft as PACKAGE_NAME, g as runningJobs, gt as MIN_WORKSPACE_PORT, h as liveUpdateFor, ht as MAX_WORKSPACE_PORT, i as liveJobsFor, in as reviewedRepositories, jn as resolveTarget, l as mergeUpdateInto, lt as workspaceUrl, m as UpdateAlreadyRunningError, mt as DEFAULT_WORKSPACE_PORT, n as deleteReview$1, nn as recentWorkspaces, q as MANAGED_ROOT, rt as ensureServer, tt as bootstrapUrl, u as updateReview, v as recordKissRun, w as record$1, x as runJob, yt as statedWorkspacePort, zn as writeAgentPreference, zt as progressSteps } from "./delete_review-D52wkt66.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.
 
@@ -1455,7 +1495,6 @@ function batchQueueLines(rows) {
 }
 function notQueuedBecause(subject, result) {
 	switch (result) {
-		case "complete": return `${subject} is marked complete. Move it back to In progress in the workspace to queue it.`;
 		case "full": return `${subject}, because the review queue is full. It holds 50 reviews at most.`;
 		default: return `${subject}, because the review queue could not be saved.`;
 	}
@@ -1468,7 +1507,6 @@ function reviewQueued(result) {
 	switch (result) {
 		case "added": return "Added to review queue.";
 		case "already": return "Already in your review queue.";
-		case "complete": return "Not added to your review queue: this review is marked complete. Move it back to In progress in the workspace to queue it.";
 		case "full": return `Not added to your review queue: it is full, and holds 50 reviews at most.`;
 		default: return "Not added to your review queue: the queue could not be saved.";
 	}