bstack 0.2.2 → 1.0.0

package/README.md

@@ -1,22 +1,23 @@
 # bstack
 
-`bstack` turns a series of commits on a local branch into native GitHub stacked pull requests.
+Convert series of commits in a local branch into native GitHub stacked pull requests.
 
 ## Install
 
-Requirements:
+```bash
+npm install -g bstack
+```
 
-- Node.js 20+
-- `gh cli` plus the `github/gh-stack` extension (authenticated)
+Install and authenticate the GitHub CLI with the `github/gh-stack` extension:
 
-```bash
+```
+gh auth login
 gh extension install github/gh-stack
-npm install bstack -g
 ```
 
 ## Use
 
-Create one commit per reviewable change, then publish the stack:
+Create one commit per change, then publish the stack:
 
 ```bash
 git switch -c my-feature
@@ -25,7 +26,9 @@ git commit -am "feat: add the API"
 bstack
 ```
 
-Run `bstack` again after amending or rebasing commits. New PRs are drafts unless you pass `--open`.
+Run `bstack` again after amending or rebasing commits.
+
+New PRs are ready for review by default. Pass `--draft` to create draft PRs.
 
 Checkout a stack through one of its PRs:
 
@@ -34,24 +37,9 @@ bstack checkout 123
 bstack checkout https://github.com/owner/repo/pull/123
 ```
 
-The first publish adds a stable `Bstack-Id` trailer to each commit and rewrites their hashes. The working tree must be clean. Merge commits and signed commits that need trailers are not supported.
-
 Use `--dry-run` to inspect without publishing and `--quiet` to hide progress logs.
 
-## Develop
-
-Install dependencies and run the checks with pnpm:
+## References
 
-```bash
-pnpm install
-pnpm run type-check
-pnpm test
-pnpm run lint
-```
-
-Build the Node.js CLI with tsdown:
-
-```bash
-pnpm run build
-node dist/bstack.js --help
-```
+- [ezyang/ghstack](https://github.com/ezyang/ghstack)
+- [github/gh-stack](https://github.com/github/gh-stack)

package/dist/bstack.js

@@ -2,10 +2,11 @@
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { z } from "zod";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 //#region package.json
-var version = "0.2.2";
+var version = "1.0.0";
 //#endregion
 //#region src/command.ts
 var CommandError = class extends Error {
@@ -82,14 +83,14 @@ function checkoutStack(repository, github, options) {
 }
 //#endregion
 //#region src/identity.ts
-const trailerPattern = /^Bstack-Id:\s*(\S+)\s*$/gim;
+const trailerPattern = /^bstack-id:\s*(\S+)\s*$/gm;
 function readChangeId(message) {
 	const matches = [...message.matchAll(trailerPattern)];
-	if (matches.length > 1) throw new Error("A commit contains more than one Bstack-Id trailer");
+	if (matches.length > 1) throw new Error("A commit contains more than one bstack-id trailer");
 	return matches[0]?.[1];
 }
 function addChangeId(message, changeId) {
-	return `${message.trimEnd()}\n\nBstack-Id: ${changeId}\n`;
+	return `${message.trimEnd()}\n\nbstack-id: ${changeId}\n`;
 }
 function newChangeId() {
 	return randomUUID().replaceAll("-", "");
@@ -128,7 +129,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*$/i.test(line)).join("\n").trim().split("\n");
+	const [subject = "Untitled change", ...bodyLines] = message.split("\n").filter((line) => !/^bstack-id:\s*\S+\s*$/.test(line)).join("\n").trim().split("\n");
 	return {
 		subject,
 		body: bodyLines.join("\n").trim()
@@ -230,7 +231,7 @@ var GitRepository = class {
 			oid
 		]).stdout));
 	}
-	ensureChangeIds(commits, dryRun) {
+	ensureChangeIds(commits, dryRun, userLogin) {
 		const assigned = commits.map((commit) => commit.changeId ?? newChangeId());
 		const needsRewrite = commits.some((commit) => commit.changeId === void 0);
 		let parent = commits[0]?.parent;
@@ -268,7 +269,7 @@ var GitRepository = class {
 				oid,
 				subject,
 				body,
-				remoteBranch: `bstack/${id}`
+				remoteBranch: `bstack/${userLogin}/${id}`
 			};
 		});
 	}
@@ -313,6 +314,19 @@ var GitRepository = class {
 };
 //#endregion
 //#region src/github.ts
+const pullRequestSchema = z.object({
+	number: z.number(),
+	url: z.string(),
+	state: z.enum([
+		"OPEN",
+		"CLOSED",
+		"MERGED"
+	]),
+	title: z.string(),
+	body: z.string(),
+	isDraft: z.boolean()
+});
+const stackSchema = z.object({ number: z.number() });
 var GhPlatform = class {
 	cwd;
 	runner;
@@ -331,6 +345,14 @@ var GhPlatform = class {
 		]);
 		this.gh(["stack", "--version"]);
 	}
+	currentUserLogin() {
+		return z.string().min(1).parse(this.gh([
+			"api",
+			"user",
+			"--jq",
+			".login"
+		]).stdout.trim());
+	}
 	defaultBranch() {
 		return this.gh([
 			"repo",
@@ -354,9 +376,8 @@ var GhPlatform = class {
 			"--json",
 			"number,url,state,title,body,isDraft"
 		]).stdout;
-		const candidates = JSON.parse(raw);
-		const selected = candidates.find((pr) => pr.state === "OPEN") ?? candidates.find((pr) => pr.state === "MERGED");
-		return selected ? normalizePullRequest(selected) : void 0;
+		const candidates = pullRequestSchema.array().parse(JSON.parse(raw));
+		return candidates.find((pr) => pr.state === "OPEN") ?? candidates.find((pr) => pr.state === "MERGED");
 	}
 	pullRequest(number) {
 		const raw = this.gh([
@@ -366,9 +387,9 @@ var GhPlatform = class {
 			"--json",
 			"number,url,state,title,body,isDraft"
 		]).stdout;
-		return normalizePullRequest(JSON.parse(raw));
+		return pullRequestSchema.parse(JSON.parse(raw));
 	}
-	createPullRequest(change, base, open) {
+	createPullRequest(change, base, draft) {
 		const args = [
 			"pr",
 			"create",
@@ -381,13 +402,13 @@ var GhPlatform = class {
 			"--body",
 			change.body
 		];
-		if (!open) args.push("--draft");
+		if (draft) args.push("--draft");
 		this.gh(args);
 		const created = this.pullRequestForBranch(change.remoteBranch);
 		if (!created) throw new Error(`GitHub did not return the PR created for ${change.remoteBranch}`);
 		return created;
 	}
-	linkStack(branches, base, remote, open) {
+	linkStack(branches, base, remote, draft) {
 		const args = [
 			"stack",
 			"link",
@@ -396,18 +417,18 @@ var GhPlatform = class {
 			"--remote",
 			remote
 		];
-		if (open) args.push("--open");
+		if (!draft) args.push("--open");
 		args.push(...branches);
 		this.gh(args);
 	}
-	appendToStack(stackNumber, branches, remote, open) {
+	appendToStack(stackNumber, branches, remote, draft) {
 		const args = [
 			"stack",
 			"link",
 			"--remote",
 			remote
 		];
-		if (open) args.push("--open");
+		if (!draft) args.push("--open");
 		args.push(String(stackNumber), ...branches);
 		this.gh(args);
 	}
@@ -418,6 +439,15 @@ var GhPlatform = class {
 			String(stackNumber)
 		]);
 	}
+	editPullRequestBase(pr, base) {
+		this.gh([
+			"pr",
+			"edit",
+			String(pr.number),
+			"--base",
+			base
+		]);
+	}
 	editPullRequest(pr, change) {
 		if (pr.title === change.subject && pr.body === change.body) return;
 		this.gh([
@@ -432,7 +462,7 @@ var GhPlatform = class {
 	}
 	stackNumberForPullRequest(prNumber) {
 		const raw = this.gh(["api", `repos/{owner}/{repo}/stacks?pull_request=${prNumber}`]).stdout;
-		return JSON.parse(raw)[0]?.number;
+		return stackSchema.array().parse(JSON.parse(raw))[0]?.number;
 	}
 	pullRequestHead(reference) {
 		return this.gh([
@@ -453,13 +483,6 @@ var GhPlatform = class {
 		]);
 	}
 };
-function normalizePullRequest(pr) {
-	if (pr.state !== "OPEN" && pr.state !== "CLOSED" && pr.state !== "MERGED") throw new Error(`GitHub returned an unknown PR state: ${pr.state}`);
-	return {
-		...pr,
-		state: pr.state
-	};
-}
 //#endregion
 //#region src/reporter.ts
 var ConsoleReporter = class {
@@ -477,6 +500,22 @@ const emptyState = () => ({
 	schemaVersion: 1,
 	stacks: []
 });
+const storedChangeSchema = z.object({
+	id: z.string(),
+	remoteBranch: z.string(),
+	pullRequest: z.number(),
+	url: z.string()
+});
+const storedStackSchema = z.object({
+	remote: z.string(),
+	base: z.string(),
+	stackNumber: z.number().optional(),
+	changes: storedChangeSchema.array()
+});
+const stateSchema = z.object({
+	schemaVersion: z.literal(1),
+	stacks: storedStackSchema.array()
+});
 var StateStore = class {
 	path;
 	constructor(path) {
@@ -484,11 +523,21 @@ var StateStore = class {
 	}
 	read() {
 		try {
-			const parsed = JSON.parse(readFileSync(this.path, "utf8"));
-			if (!isState(parsed)) throw new Error(`Unsupported bstack state in ${this.path}`);
-			return parsed;
+			return {
+				schemaVersion: 1,
+				stacks: stateSchema.parse(JSON.parse(readFileSync(this.path, "utf8"))).stacks.map((stack) => {
+					const stored = {
+						remote: stack.remote,
+						base: stack.base,
+						changes: stack.changes
+					};
+					if (stack.stackNumber !== void 0) stored.stackNumber = stack.stackNumber;
+					return stored;
+				})
+			};
 		} catch (error) {
-			if (isMissingFile(error)) return emptyState();
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return emptyState();
+			if (error instanceof z.ZodError) throw new Error(`Unsupported bstack state in ${this.path}`, { cause: error });
 			throw error;
 		}
 	}
@@ -504,14 +553,6 @@ var StateStore = class {
 		return matches[0];
 	}
 };
-function isMissingFile(error) {
-	return error instanceof Error && "code" in error && error.code === "ENOENT";
-}
-function isState(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const candidate = value;
-	return candidate.schemaVersion === 1 && Array.isArray(candidate.stacks);
-}
 //#endregion
 //#region src/sync.ts
 function syncStack(repository, github, options) {
@@ -521,7 +562,9 @@ function syncStack(repository, github, options) {
 	github.assertReady();
 	const remote = repository.resolveRemote(options.remote);
 	const base = options.base ?? github.defaultBranch();
+	const userLogin = github.currentUserLogin();
 	reporter.progress(`Using ${remote} as the remote and ${base} as the stack base`);
+	reporter.progress(`Using ${userLogin} as the remote branch namespace`);
 	reporter.progress(`Fetching ${remote}/${base}`);
 	const remoteBase = repository.fetchBase(remote, base);
 	const baseOid = repository.mergeBase("HEAD", remoteBase);
@@ -531,7 +574,7 @@ function syncStack(repository, github, options) {
 	const rewritten = commits.some((commit) => commit.changeId === void 0);
 	if (rewritten) reporter.progress(options.dryRun ? "Stable change IDs would be added to the commits" : "Adding stable change IDs to the commits");
 	else reporter.progress("All commits already have stable change IDs");
-	const changes = repository.ensureChangeIds(commits, options.dryRun);
+	const changes = repository.ensureChangeIds(commits, options.dryRun, userLogin);
 	if (options.dryRun) {
 		reporter.progress("Dry run complete; no commits or remote branches were changed");
 		return {
@@ -545,7 +588,7 @@ 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);
+	const evolution = analyzeEvolution(previous, changes, github, repository.currentBranch() === "");
 	reporter.progress(`Publishing ${changes.length} protected remote ref${changes.length === 1 ? "" : "s"}`);
 	repository.pushChanges(remote, changes);
 	reporter.progress("Looking up existing pull requests");
@@ -554,28 +597,32 @@ function syncStack(repository, github, options) {
 	if (changes.length === 1) {
 		if (evolution.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");
-		pullRequests = [existing[0] ?? github.createPullRequest(changes[0], base, options.open)];
+		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);
+			try {
+				github.editPullRequestBase(pullRequest, base);
+			} catch (error) {
+				restorePreviousStack(github, previous, base, remote, reporter, error);
+			}
+		}
+		pullRequests = [pullRequest];
 	} else {
 		if (evolution.kind === "full") {
 			reporter.progress(`Linking ${changes.length} pull requests as a native GitHub stack`);
-			github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.open);
+			github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.draft);
 		} else if (evolution.kind === "rebuild") {
-			reporter.progress(`Rebuilding stack #${evolution.stackNumber} to insert pull requests`);
+			reporter.progress(`Rebuilding stack #${evolution.stackNumber} to ${evolution.action} pull requests`);
 			github.unstack(evolution.stackNumber);
 			try {
-				github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.open);
+				github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.draft);
 			} catch (error) {
-				reporter.progress("Rebuild failed; restoring the previous native GitHub stack");
-				try {
-					github.linkStack(previous.changes.map((change) => change.remoteBranch), base, remote, false);
-				} catch (rollbackError) {
-					throw new Error(`Stack rebuild failed: ${errorMessage(error)}\nRestoring the previous stack also failed: ${errorMessage(rollbackError)}`);
-				}
-				throw 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.open);
+			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 reporter.progress("The native GitHub stack already has the correct members");
 		pullRequests = changes.map((change, index) => {
@@ -589,20 +636,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) : previous?.stackNumber ?? (pullRequests.length > 1 ? github.stackNumberForPullRequest(pullRequests[0].number) : void 0);
+	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 synchronizedChanges = changes.map((change, index) => ({
 		id: change.id,
 		remoteBranch: change.remoteBranch,
 		pullRequest: pullRequests[index].number,
 		url: pullRequests[index].url
 	}));
-	const storedChanges = evolution.kind === "partial" && previous ? [...synchronizedChanges, ...previous.changes.slice(evolution.previousOffset + changes.length)] : synchronizedChanges;
-	writeUpdatedState(store, state, previous, {
+	const stored = {
 		remote,
 		base,
-		...stackNumber === void 0 ? {} : { stackNumber },
-		changes: storedChanges
-	});
+		changes: evolution.kind === "partial" && previous ? [...synchronizedChanges, ...previous.changes.slice(evolution.previousOffset + changes.length)] : synchronizedChanges
+	};
+	if (stackNumber !== void 0) stored.stackNumber = stackNumber;
+	writeUpdatedState(store, state, previous, stored);
 	reporter.progress("Saved the local stack state");
 	return {
 		base,
@@ -614,46 +661,69 @@ function syncStack(repository, github, options) {
 		}))
 	};
 }
-function analyzeEvolution(previous, changes, github) {
+function analyzeEvolution(previous, changes, github, preserveHigherChanges) {
 	if (!previous) return { kind: "full" };
 	const previousIds = previous.changes.map((change) => change.id);
 	const currentIds = changes.map((change) => change.id);
-	if (isSubsequence(previousIds, currentIds)) {
+	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");
+	const removed = previous.changes.filter((change) => !currentIdSet.has(change.id));
+	const added = changes.filter((change) => !previousIdSet.has(change.id));
+	if (removed.length === 0) {
 		if (previousIds.every((id, index) => currentIds[index] === id)) return { kind: "full" };
 		const stackNumber = previous.stackNumber ?? github.stackNumberForPullRequest(previous.changes[0].pullRequest);
 		return stackNumber === void 0 ? { kind: "full" } : {
 			kind: "rebuild",
-			stackNumber
+			stackNumber,
+			action: "insert"
 		};
 	}
 	const firstCurrentIndex = previousIds.indexOf(currentIds[0]);
-	if (firstCurrentIndex === -1) throw new Error("The current commits do not continue the previously submitted stack");
-	const removedPrefix = previous.changes.slice(0, firstCurrentIndex);
-	for (const removed of removedPrefix) if (github.pullRequest(removed.pullRequest).state !== "MERGED") throw new Error("Submitted commits may only disappear from the bottom after their pull requests are merged");
-	const surviving = previousIds.slice(firstCurrentIndex);
-	const sharedLength = Math.min(surviving.length, currentIds.length);
-	for (let index = 0; index < sharedLength; index++) if (surviving[index] !== currentIds[index]) throw new Error("Reordering or removing submitted commits is not supported yet. Restore the original order before syncing");
-	if (currentIds.length < surviving.length) return {
-		kind: "partial",
-		previousOffset: firstCurrentIndex
+	const isPreviousSlice = firstCurrentIndex >= 0 && currentIds.every((id, index) => previousIds[firstCurrentIndex + index] === id);
+	if (preserveHigherChanges && added.length === 0 && isPreviousSlice && firstCurrentIndex + currentIds.length < previousIds.length) {
+		if (previous.changes.slice(0, firstCurrentIndex).every((change) => github.pullRequest(change.pullRequest).state === "MERGED")) return {
+			kind: "partial",
+			previousOffset: firstCurrentIndex
+		};
+	}
+	const removedPrefixWasMerged = removed.every((change, index) => previous.changes[index] === change) && removed.every((change) => github.pullRequest(change.pullRequest).state === "MERGED");
+	const survivingIds = previousIds.slice(removed.length);
+	const onlyAppendedAfterMergedPrefix = removedPrefixWasMerged && survivingIds.every((id, index) => currentIds[index] === id) && currentIds.slice(survivingIds.length).every((id) => !previousIdSet.has(id));
+	if (removedPrefixWasMerged && added.length === 0) return { kind: "skip" };
+	if (onlyAppendedAfterMergedPrefix) {
+		if (previous.stackNumber === void 0) throw new Error("Cannot append after a merge because the native GitHub stack number is missing from local state");
+		return {
+			kind: "append",
+			stackNumber: previous.stackNumber,
+			branches: added.map((change) => change.remoteBranch)
+		};
+	}
+	const stackNumber = previous.stackNumber ?? github.stackNumberForPullRequest(previous.changes[0].pullRequest);
+	if (stackNumber === void 0) throw new Error("Cannot remove submitted commits because the native GitHub stack number is missing from local state");
+	if (changes.length === 1) return {
+		kind: "collapse",
+		stackNumber
 	};
-	const appended = changes.slice(surviving.length);
-	if (removedPrefix.length === 0) return { kind: "full" };
-	if (appended.length === 0) return { kind: "skip" };
-	if (previous.stackNumber === void 0) throw new Error("Cannot append after a merge because the native GitHub stack number is missing from local state");
 	return {
-		kind: "append",
-		stackNumber: previous.stackNumber,
-		branches: appended.map((change) => change.remoteBranch)
+		kind: "rebuild",
+		stackNumber,
+		action: added.length === 0 ? "remove" : "update"
 	};
 }
-function isSubsequence(expected, actual) {
-	let expectedIndex = 0;
-	for (const value of actual) if (value === expected[expectedIndex]) expectedIndex++;
-	return expectedIndex === expected.length;
+function sameValues(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
 }
-function errorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
+function restorePreviousStack(github, previous, base, remote, reporter, rebuildError) {
+	const rebuildMessage = rebuildError instanceof Error ? rebuildError.message : String(rebuildError);
+	reporter.progress("Rebuild failed; restoring the previous native GitHub stack");
+	try {
+		github.linkStack(previous.changes.map((change) => change.remoteBranch), base, remote, true);
+	} catch (rollbackError) {
+		const rollbackMessage = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+		throw new Error(`Stack rebuild failed: ${rebuildMessage}\nRestoring the previous stack also failed: ${rollbackMessage}`);
+	}
+	throw rebuildError;
 }
 function writeUpdatedState(store, state, previous, updated) {
 	const stacks = previous ? state.stacks.map((stack) => stack === previous ? updated : stack) : [...state.stacks, updated];
@@ -673,7 +743,7 @@ Usage:
 Options:
   --base <branch>    Stack trunk; defaults to the GitHub default branch
   --remote <name>    Git remote; defaults to remote.pushDefault or origin
-  --open             Create PRs ready for review instead of drafts
+  --draft            Create draft PRs instead of ready-for-review PRs
   --dry-run          Inspect the stack without rewriting commits or pushing
   --quiet            Hide progress logs; the final summary is still printed
   --same-base        Refuse checkout if it would change the current merge base
@@ -687,7 +757,7 @@ function main() {
 		options: {
 			base: { type: "string" },
 			remote: { type: "string" },
-			open: {
+			draft: {
 				type: "boolean",
 				default: false
 			},
@@ -746,7 +816,7 @@ function main() {
 	const result = syncStack(repository, github, {
 		base: values.base,
 		remote: values.remote,
-		open: values.open,
+		draft: values.draft,
 		dryRun: values["dry-run"],
 		reporter
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bstack",
-  "version": "0.2.2",
+  "version": "1.0.0",
   "packageManager": "pnpm@11.5.1",
   "description": "Create native GitHub stacked pull requests from a linear series of commits",
   "repository": {
@@ -38,5 +38,8 @@
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vitest": "^4.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
   }
 }