bstack 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # bstack
 
-Convert series of commits in a local branch into native GitHub stacked pull requests.
+Convert a series of commits in a local branch into a native GitHub stack of pull requests.
 
 ## Install
 
@@ -17,7 +17,7 @@ gh extension install github/gh-stack
 
 ## Use
 
-Create one commit per change, then publish the stack:
+Create one commit per change, then sync the stack:
 
 ```bash
 git switch -c my-feature
@@ -37,7 +37,7 @@ bstack checkout 123
 bstack checkout https://github.com/owner/repo/pull/123
 ```
 
-Use `--dry-run` to inspect without publishing and `--quiet` to hide progress logs.
+Use `--dry-run` to inspect without syncing and `--quiet` to hide progress logs.
 
 ## References
 

package/dist/bstack.js

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 //#region package.json
-var version = "1.0.0";
+var version = "1.0.1";
 //#endregion
 //#region src/command.ts
 var CommandError = class extends Error {
@@ -75,24 +75,26 @@ function checkoutStack(repository, github, options) {
 	}
 	reporter.progress(`Checking out ${remote}/${headRef} in detached HEAD state`);
 	repository.checkout(target);
-	reporter.progress("Checkout complete; amend the commits and run bstack to publish updates");
+	reporter.progress("Checkout complete; amend the commits and run bstack to sync updates");
 	return {
 		headRef,
 		delegated: false
 	};
 }
 //#endregion
-//#region src/identity.ts
-const trailerPattern = /^bstack-id:\s*(\S+)\s*$/gm;
+//#region src/commit.ts
+const CHANGE_ID_TRAILER = "bstack-id";
+const changeIdTrailerPattern = new RegExp(`^${CHANGE_ID_TRAILER}:\\s*(\\S+)\\s*$`, "gm");
+const changeIdTrailerLinePattern = new RegExp(`^${CHANGE_ID_TRAILER}:\\s*\\S+\\s*$`);
 function readChangeId(message) {
-	const matches = [...message.matchAll(trailerPattern)];
-	if (matches.length > 1) throw new Error("A commit contains more than one bstack-id trailer");
+	const matches = [...message.matchAll(changeIdTrailerPattern)];
+	if (matches.length > 1) throw new Error(`A commit contains more than one ${CHANGE_ID_TRAILER} trailer`);
 	return matches[0]?.[1];
 }
 function addChangeId(message, changeId) {
-	return `${message.trimEnd()}\n\nbstack-id: ${changeId}\n`;
+	return `${message.trimEnd()}\n\n${CHANGE_ID_TRAILER}: ${changeId}\n`;
 }
-function newChangeId() {
+function generateChangeId() {
 	return randomUUID().replaceAll("-", "");
 }
 function parseRawCommit(oid, raw) {
@@ -129,7 +131,7 @@ function rewriteCommit(commit, parent, message) {
 	return `${rewrittenHeaders.join("\n")}\n\n${message}`;
 }
 function splitCommitMessage(message) {
-	const [subject = "Untitled change", ...bodyLines] = message.split("\n").filter((line) => !/^bstack-id:\s*\S+\s*$/.test(line)).join("\n").trim().split("\n");
+	const [subject = "Untitled change", ...bodyLines] = message.split("\n").filter((line) => !changeIdTrailerLinePattern.test(line)).join("\n").trim().split("\n");
 	return {
 		subject,
 		body: bodyLines.join("\n").trim()
@@ -152,7 +154,7 @@ var GitRepository = class {
 	}
 	assertReady() {
 		this.git(["rev-parse", "--show-toplevel"]);
-		if (this.git(["status", "--porcelain"]).stdout.trim()) throw new Error("The working tree must be clean before bstack rewrites or publishes commits");
+		if (this.git(["status", "--porcelain"]).stdout.trim()) throw new Error("The working tree must be clean before bstack rewrites commits or pushes branches");
 	}
 	currentBranch() {
 		return this.git([
@@ -232,7 +234,7 @@ var GitRepository = class {
 		]).stdout));
 	}
 	ensureChangeIds(commits, dryRun, userLogin) {
-		const assigned = commits.map((commit) => commit.changeId ?? newChangeId());
+		const assigned = commits.map((commit) => commit.changeId ?? generateChangeId());
 		const needsRewrite = commits.some((commit) => commit.changeId === void 0);
 		let parent = commits[0]?.parent;
 		const rewrittenOids = [];
@@ -327,7 +329,7 @@ const pullRequestSchema = z.object({
 	isDraft: z.boolean()
 });
 const stackSchema = z.object({ number: z.number() });
-var GhPlatform = class {
+var GitHubCliPlatform = class {
 	cwd;
 	runner;
 	constructor(cwd, runner) {
@@ -588,19 +590,19 @@ function syncStack(repository, github, options) {
 	const store = new StateStore(repository.statePath());
 	const state = store.read();
 	const previous = store.findByChangeIds(state, new Set(changes.map((change) => change.id)));
-	const evolution = analyzeEvolution(previous, changes, github, repository.currentBranch() === "");
-	reporter.progress(`Publishing ${changes.length} protected remote ref${changes.length === 1 ? "" : "s"}`);
+	const transition = analyzeStackTransition(previous, changes, github, repository.currentBranch() === "");
+	reporter.progress(`Pushing ${changes.length} remote branch${changes.length === 1 ? "" : "es"}`);
 	repository.pushChanges(remote, changes);
 	reporter.progress("Looking up existing pull requests");
 	const existing = changes.map((change) => github.pullRequestForBranch(change.remoteBranch));
 	let pullRequests;
 	if (changes.length === 1) {
-		if (evolution.kind === "partial") reporter.progress("Updating this down-stack prefix while preserving higher pull requests");
+		if (transition.kind === "partial") reporter.progress("Updating this down-stack prefix while preserving higher pull requests");
 		reporter.progress(existing[0] ? "Using the existing pull request" : "Creating a pull request");
 		const pullRequest = existing[0] ?? github.createPullRequest(changes[0], base, options.draft);
-		if (evolution.kind === "collapse") {
-			reporter.progress(`Removing omitted pull requests from stack #${evolution.stackNumber}`);
-			github.unstack(evolution.stackNumber);
+		if (transition.kind === "collapse") {
+			reporter.progress(`Removing omitted pull requests from stack #${transition.stackNumber}`);
+			github.unstack(transition.stackNumber);
 			try {
 				github.editPullRequestBase(pullRequest, base);
 			} catch (error) {
@@ -609,21 +611,21 @@ function syncStack(repository, github, options) {
 		}
 		pullRequests = [pullRequest];
 	} else {
-		if (evolution.kind === "full") {
+		if (transition.kind === "full") {
 			reporter.progress(`Linking ${changes.length} pull requests as a native GitHub stack`);
 			github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.draft);
-		} else if (evolution.kind === "rebuild") {
-			reporter.progress(`Rebuilding stack #${evolution.stackNumber} to ${evolution.action} pull requests`);
-			github.unstack(evolution.stackNumber);
+		} else if (transition.kind === "rebuild") {
+			reporter.progress(`Rebuilding stack #${transition.stackNumber} to ${transition.action} pull requests`);
+			github.unstack(transition.stackNumber);
 			try {
 				github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.draft);
 			} catch (error) {
 				restorePreviousStack(github, previous, base, remote, reporter, error);
 			}
-		} else if (evolution.kind === "append") {
-			reporter.progress(`Appending ${evolution.branches.length} pull request${evolution.branches.length === 1 ? "" : "s"} to stack #${evolution.stackNumber}`);
-			github.appendToStack(evolution.stackNumber, evolution.branches, remote, options.draft);
-		} else if (evolution.kind === "partial") reporter.progress("Updating this down-stack prefix while preserving higher pull requests");
+		} else if (transition.kind === "append") {
+			reporter.progress(`Appending ${transition.branches.length} pull request${transition.branches.length === 1 ? "" : "s"} to stack #${transition.stackNumber}`);
+			github.appendToStack(transition.stackNumber, transition.branches, remote, options.draft);
+		} else if (transition.kind === "partial") reporter.progress("Updating this down-stack prefix while preserving higher pull requests");
 		else reporter.progress("The native GitHub stack already has the correct members");
 		pullRequests = changes.map((change, index) => {
 			const pr = existing[index] ?? github.pullRequestForBranch(change.remoteBranch);
@@ -636,20 +638,20 @@ function syncStack(repository, github, options) {
 		github.editPullRequest(pr, changes[index]);
 		reporter.progress(`PR #${pr.number}: ${changes[index].subject}`);
 	}
-	const stackNumber = evolution.kind === "rebuild" ? github.stackNumberForPullRequest(pullRequests[0].number) : evolution.kind === "collapse" ? void 0 : previous?.stackNumber ?? (pullRequests.length > 1 ? github.stackNumberForPullRequest(pullRequests[0].number) : void 0);
+	const stackNumber = transition.kind === "rebuild" ? github.stackNumberForPullRequest(pullRequests[0].number) : transition.kind === "collapse" ? void 0 : previous?.stackNumber ?? (pullRequests.length > 1 ? github.stackNumberForPullRequest(pullRequests[0].number) : void 0);
 	const synchronizedChanges = changes.map((change, index) => ({
 		id: change.id,
 		remoteBranch: change.remoteBranch,
 		pullRequest: pullRequests[index].number,
 		url: pullRequests[index].url
 	}));
-	const stored = {
+	const updatedStack = {
 		remote,
 		base,
-		changes: evolution.kind === "partial" && previous ? [...synchronizedChanges, ...previous.changes.slice(evolution.previousOffset + changes.length)] : synchronizedChanges
+		changes: transition.kind === "partial" && previous ? [...synchronizedChanges, ...previous.changes.slice(transition.previousOffset + changes.length)] : synchronizedChanges
 	};
-	if (stackNumber !== void 0) stored.stackNumber = stackNumber;
-	writeUpdatedState(store, state, previous, stored);
+	if (stackNumber !== void 0) updatedStack.stackNumber = stackNumber;
+	writeUpdatedState(store, state, previous, updatedStack);
 	reporter.progress("Saved the local stack state");
 	return {
 		base,
@@ -661,13 +663,13 @@ function syncStack(repository, github, options) {
 		}))
 	};
 }
-function analyzeEvolution(previous, changes, github, preserveHigherChanges) {
+function analyzeStackTransition(previous, changes, github, preserveHigherChanges) {
 	if (!previous) return { kind: "full" };
 	const previousIds = previous.changes.map((change) => change.id);
 	const currentIds = changes.map((change) => change.id);
 	const previousIdSet = new Set(previousIds);
 	const currentIdSet = new Set(currentIds);
-	if (!sameValues(previousIds.filter((id) => currentIdSet.has(id)), currentIds.filter((id) => previousIdSet.has(id)))) throw new Error("Submitted commits cannot be reordered. Restore their original relative order before syncing");
+	if (!sameSequence(previousIds.filter((id) => currentIdSet.has(id)), currentIds.filter((id) => previousIdSet.has(id)))) throw new Error("Submitted commits cannot be reordered. Restore their original relative order before syncing");
 	const removed = previous.changes.filter((change) => !currentIdSet.has(change.id));
 	const added = changes.filter((change) => !previousIdSet.has(change.id));
 	if (removed.length === 0) {
@@ -711,7 +713,7 @@ function analyzeEvolution(previous, changes, github, preserveHigherChanges) {
 		action: added.length === 0 ? "remove" : "update"
 	};
 }
-function sameValues(left, right) {
+function sameSequence(left, right) {
 	return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 function restorePreviousStack(github, previous, base, remote, reporter, rebuildError) {
@@ -734,14 +736,14 @@ function writeUpdatedState(store, state, previous, updated) {
 }
 //#endregion
 //#region src/cli.ts
-const help = `bstack - turn a linear commit series into native GitHub stacked PRs
+const help = `bstack - turn a linear commit series into a native GitHub stack of PRs
 
 Usage:
   bstack [sync] [options]
   bstack checkout <PR-number-or-URL> [options]
 
 Options:
-  --base <branch>    Stack trunk; defaults to the GitHub default branch
+  --base <branch>    Stack base; defaults to the GitHub default branch
   --remote <name>    Git remote; defaults to remote.pushDefault or origin
   --draft            Create draft PRs instead of ready-for-review PRs
   --dry-run          Inspect the stack without rewriting commits or pushing
@@ -796,7 +798,7 @@ function main() {
 	const runner = new NodeCommandRunner();
 	const cwd = process.cwd();
 	const repository = new GitRepository(cwd, runner);
-	const github = new GhPlatform(cwd, runner);
+	const github = new GitHubCliPlatform(cwd, runner);
 	const reporter = new ConsoleReporter(!values.quiet);
 	const command = positionals[0] ?? "sync";
 	if (command === "checkout") {
@@ -820,7 +822,7 @@ function main() {
 		dryRun: values["dry-run"],
 		reporter
 	});
-	console.log(`${values["dry-run"] ? "Would publish" : "Published"} ${result.changes.length} change${result.changes.length === 1 ? "" : "s"} against ${result.base}:`);
+	console.log(`${values["dry-run"] ? "Would sync" : "Synced"} ${result.changes.length} change${result.changes.length === 1 ? "" : "s"} against ${result.base}:`);
 	for (const change of result.changes) {
 		const destination = change.pullRequest ? ` ${change.pullRequest.url}` : "";
 		console.log(`  ${change.oid.slice(0, 8)}  ${change.subject}${destination}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bstack",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "packageManager": "pnpm@11.5.1",
   "description": "Create native GitHub stacked pull requests from a linear series of commits",
   "repository": {