gh-stack 0.7.1 → 0.10.0

package/src/commands/update-prs.ts

@@ -1,11 +1,162 @@
 // gh-stack update-prs — Update PR descriptions with stack visualization
-// Port of reference/gh-stack-update-pr.sh
+//
+// The visualization is rendered entirely from local metadata (PR number,
+// cached title, stack position) plus a single repo-identity lookup for URLs —
+// no per-PR API call. `submit` reuses `refreshStackViz` and skips PATCHing any
+// PR whose rendered block hasn't changed (see issue #16). Review/CI status is
+// intentionally NOT shown here; that's tracked out-of-band.
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
+import { createHash } from "node:crypto";
 import * as git from "../lib/git.ts";
-import { findStackForBranch, getOrderedBranches } from "../lib/metadata.ts";
+import {
+  findStackForBranch,
+  getOrderedBranches,
+  stackBase,
+  writeMetadata,
+} from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";
-import { getPrInfo, getPrBody, updatePrBody, reviewEmoji } from "../lib/github.ts";
+import { getPrInfo, getPrBody, updatePrBody, getRepoNwo, prUrlFor } from "../lib/github.ts";
+import type { StackMetadata, Stack } from "../types.ts";
+
+/** The ref a stack is rooted on, for rendering the base node of the viz. */
+export interface BaseRef {
+  label: string; // "main" or a branch name (for split stacks)
+  prNumber?: number | null;
+  prUrl?: string | null;
+}
+
+export interface BranchPrInfo {
+  branch: string;
+  prNumber: number | null;
+  prTitle: string;
+  prUrl: string | null;
+}
+
+/** Derive a readable PR title from a branch name (fallback when uncached). */
+export function branchToTitle(branch: string): string {
+  let name = branch.includes("/") ? branch.split("/").slice(1).join("/") : branch;
+  name = name.replace(/-/g, " ");
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/**
+ * Resolve the base node for a stack's visualization. For a split stack whose
+ * base is a branch in another stack, link to that branch's PR. The URL is
+ * constructed locally from the repo identity — no API call.
+ */
+export async function resolveBaseRef(
+  meta: StackMetadata,
+  stack: Stack,
+  nwo: string | null,
+): Promise<BaseRef> {
+  const base = stackBase(stack);
+  if (base === "main" || base === "master") return { label: base };
+
+  const ownerName = findStackForBranch(meta, base);
+  const prNumber = ownerName ? (meta.stacks[ownerName]?.branches[base]?.pr ?? null) : null;
+  return { label: base, prNumber, prUrl: prNumber ? prUrlFor(nwo, prNumber) : null };
+}
+
+/** Build a BranchPrInfo from metadata alone (no network). */
+function toBranchInfo(stack: Stack, branch: string, nwo: string | null): BranchPrInfo {
+  const bm = stack.branches[branch]!;
+  const prNumber = bm.pr ?? null;
+  return {
+    branch,
+    prNumber,
+    prTitle: bm.prTitle || bm.description || branchToTitle(branch),
+    prUrl: prNumber ? prUrlFor(nwo, prNumber) : null,
+  };
+}
+
+/**
+ * Fill in missing cached PR titles (one-time, e.g. right after migrating to v3
+ * or adopting existing PRs). Fetches only the branches that lack a title, in
+ * parallel; subsequent submits read straight from the cache. Returns true if
+ * any title was written.
+ */
+async function backfillTitles(stack: Stack, ordered: string[]): Promise<boolean> {
+  const missing = ordered.filter((b) => {
+    const bm = stack.branches[b]!;
+    return bm.pr != null && !bm.prTitle;
+  });
+  if (missing.length === 0) return false;
+
+  await mapLimit(missing, 8, async (branch) => {
+    const bm = stack.branches[branch]!;
+    const info = await getPrInfo(bm.pr!);
+    if (info?.title) bm.prTitle = info.title;
+  });
+  return true;
+}
+
+function vizHash(viz: string): string {
+  return createHash("sha1").update(viz).digest("hex");
+}
+
+/** Splice the rendered viz block into a PR body, replacing any existing one. */
+function mergeViz(body: string, viz: string): string {
+  let base = body;
+  const idx = base.indexOf("### 📚 Stacked on");
+  if (idx !== -1) base = base.slice(0, idx).trimEnd();
+  return base ? `${base}\n\n${viz}` : viz;
+}
+
+export interface VizResult {
+  updated: number; // PRs whose description we PATCHed
+  unchanged: number; // PRs skipped because their rendered block was identical
+  skipped: number; // branches with no PR
+  dirty: boolean; // metadata mutated (caller should persist)
+}
+
+/**
+ * Refresh the stack visualization across a stack's PRs. Renders every block
+ * locally, then PATCHes only the PRs whose block actually changed (unless
+ * `force`), running the surviving PATCHes concurrently.
+ */
+export async function refreshStackViz(
+  meta: StackMetadata,
+  stack: Stack,
+  ordered: string[],
+  opts: { force?: boolean } = {},
+): Promise<VizResult> {
+  const force = opts.force ?? false;
+  const nwo = await getRepoNwo();
+
+  let dirty = await backfillTitles(stack, ordered);
+
+  const branchInfos = ordered.map((b) => toBranchInfo(stack, b, nwo));
+  const baseRef = await resolveBaseRef(meta, stack, nwo);
+
+  // Render every block locally and decide what needs writing — no network yet.
+  const plans = branchInfos
+    .map((info, i) => ({ info, i }))
+    .filter(({ info }) => info.prNumber != null)
+    .map(({ info, i }) => {
+      const viz = buildStackViz(branchInfos, i, baseRef);
+      const hash = vizHash(viz);
+      const bm = stack.branches[info.branch]!;
+      return { info, viz, hash, bm, needsUpdate: force || bm.vizHash !== hash };
+    });
+
+  const toUpdate = plans.filter((plan) => plan.needsUpdate);
+  const unchanged = plans.length - toUpdate.length;
+  const skipped = branchInfos.length - plans.length;
+
+  const oks = await mapLimit(toUpdate, 8, async (plan) => {
+    const body = await getPrBody(plan.info.prNumber!);
+    if (body === null) return false;
+    const ok = await updatePrBody(plan.info.prNumber!, mergeViz(body, plan.viz));
+    if (ok) plan.bm.vizHash = plan.hash;
+    return ok;
+  });
+
+  const updated = oks.filter(Boolean).length;
+  if (updated > 0) dirty = true;
+
+  return { updated, unchanged, skipped, dirty };
+}
 
 export default async function updatePrs(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -13,14 +164,16 @@ export default async function updatePrs(args: string[]): Promise<void> {
 gh-stack update-prs — Update PR descriptions with stack visualization
 
 USAGE
-  gh-stack update-prs
+  gh-stack update-prs [--force]
 
 Updates all PRs in the current stack with a standardized stack section
-showing the tree structure, PR links, and review status.
+showing the tree structure, PR links, and per-PR stack index. By default
+PRs whose rendered block is unchanged are skipped; --force rewrites all.
 `);
     return;
   }
 
+  const force = args.includes("--force");
   const meta = await ensureMetadata();
   const branch = await git.currentBranch();
   const stackName = findStackForBranch(meta, branch);
@@ -38,117 +191,43 @@ showing the tree structure, PR links, and review status.
   p.log.info(`Found ${ordered.length} branch(es) in stack`);
   console.log();
 
-  // Collect PR info for all branches
   const s = p.spinner();
-  s.start("Fetching PR info from GitHub...");
-
-  interface BranchPrInfo {
-    branch: string;
-    prNumber: number | null;
-    prTitle: string;
-    prUrl: string | null;
-    reviewEmojiStr: string;
-  }
+  s.start("Updating PR descriptions...");
+  const result = await refreshStackViz(meta, stack, ordered, { force });
+  s.stop("Done");
 
-  const branchInfos: BranchPrInfo[] = [];
-
-  for (const branchName of ordered) {
-    const branchMeta = stack.branches[branchName]!;
-    const prNumber = branchMeta.pr ?? null;
-    let prTitle = branchMeta.description || branchName;
-    let prUrl: string | null = null;
-    let review = "PENDING";
-
-    if (prNumber) {
-      const info = await getPrInfo(prNumber);
-      if (info) {
-        prTitle = info.title || prTitle;
-        prUrl = info.url;
-        review = info.reviewDecision || "PENDING";
-      }
-    }
-
-    branchInfos.push({
-      branch: branchName,
-      prNumber,
-      prTitle,
-      prUrl,
-      reviewEmojiStr: reviewEmoji(review),
-    });
-  }
-
-  s.stop("Fetched PR info");
-
-  // Update each PR
-  let updated = 0;
-  let skipped = 0;
-
-  for (let targetIdx = 0; targetIdx < branchInfos.length; targetIdx++) {
-    const target = branchInfos[targetIdx]!;
-
-    if (!target.prNumber) {
-      p.log.info(`${pc.dim("⏭")} ${target.branch} — no PR, skipping`);
-      skipped++;
-      continue;
-    }
-
-    // Build stack visualization for this PR
-    const stackViz = buildStackViz(branchInfos, targetIdx);
-
-    // Get current PR body and replace/append stack section
-    const currentBody = await getPrBody(target.prNumber);
-    if (currentBody === null) {
-      p.log.warn(`Could not fetch body for PR #${target.prNumber}`);
-      skipped++;
-      continue;
-    }
-
-    // Remove existing stack section
-    let updatedBody = currentBody;
-    const stackSectionIdx = updatedBody.indexOf("### 📚 Stacked on");
-    if (stackSectionIdx !== -1) {
-      updatedBody = updatedBody.slice(0, stackSectionIdx).trimEnd();
-    }
-
-    // Append new stack section
-    const newBody = updatedBody ? `${updatedBody}\n\n${stackViz}` : stackViz;
-
-    // Update PR
-    const ok = await updatePrBody(target.prNumber, newBody);
-    if (ok) {
-      p.log.success(`PR #${target.prNumber} ${target.prTitle}`);
-      updated++;
-    } else {
-      p.log.error(`Failed to update PR #${target.prNumber}`);
-    }
-  }
+  if (result.dirty) await writeMetadata(meta);
 
   console.log();
   p.outro(
     pc.green(
-      `Done! Updated ${updated} PR(s)${skipped > 0 ? `, skipped ${skipped} without PRs` : ""}`,
+      `Updated ${result.updated} PR(s)` +
+        (result.unchanged > 0 ? `, ${result.unchanged} unchanged` : "") +
+        (result.skipped > 0 ? `, ${result.skipped} without PRs` : ""),
     ),
   );
 }
 
-interface BranchPrInfo {
-  branch: string;
-  prNumber: number | null;
-  prTitle: string;
-  prUrl: string | null;
-  reviewEmojiStr: string;
-}
-
-export function buildStackViz(branches: BranchPrInfo[], targetIndex: number): string {
+export function buildStackViz(
+  branches: BranchPrInfo[],
+  targetIndex: number,
+  base: BaseRef = { label: "main" },
+): string {
   const lines: string[] = ["### 📚 Stacked on", ""];
 
+  // Base node: link to the base PR if there is one (split stacks), else the
+  // plain ref name. `**bold**` renders in markdown but not inside <pre>.
+  const baseLink = base.prNumber
+    ? `${base.prUrl ? `<a href="${base.prUrl}">#${base.prNumber}</a>` : `#${base.prNumber}`} ${base.label}`
+    : null;
+
   if (branches.length === 1) {
-    lines.push("- ⚫ **main**");
+    lines.push(`- ⚫ ${baseLink ?? `**${base.label}**`}`);
     return lines.join("\n");
   }
 
   lines.push("<pre>");
-  lines.push("⚫ main");
+  lines.push(`⚫ ${baseLink ?? base.label}`);
   lines.push("┃");
 
   for (let i = 0; i < branches.length; i++) {
@@ -170,7 +249,9 @@ export function buildStackViz(branches: BranchPrInfo[], targetIndex: number): st
     // Tree character
     const tree = isLast ? "┗━" : "┣━";
 
-    lines.push(`${tree} ${info.reviewEmojiStr} ${prLink} ${info.prTitle}${marker}`);
+    // Leading `N.` is the branch's 1-based position in the stack — makes it
+    // easy to tell which PR is #6 in a 12-PR stack at a glance.
+    lines.push(`${tree} ${i + 1}. ${prLink} ${info.prTitle}${marker}`);
 
     if (!isLast) {
       lines.push("┃");
@@ -180,3 +261,23 @@ export function buildStackViz(branches: BranchPrInfo[], targetIndex: number): st
   lines.push("</pre>");
   return lines.join("\n");
 }
+
+/** Run `fn` over `items` with at most `limit` concurrent in flight. */
+async function mapLimit<T, R>(
+  items: T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results = Array.from<R>({ length: items.length });
+  let next = 0;
+  async function worker(): Promise<void> {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i]!, i);
+    }
+  }
+  const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}

package/src/index.ts

@@ -69,6 +69,14 @@ switch (command) {
     await (await import("./commands/delete.ts")).default(commandArgs);
     break;
 
+  case "split":
+    await (await import("./commands/split.ts")).default(commandArgs);
+    break;
+
+  case "rename":
+    await (await import("./commands/rename.ts")).default(commandArgs);
+    break;
+
   case "checkout":
   case "co":
     await (await import("./commands/checkout.ts")).default(commandArgs);
@@ -103,6 +111,18 @@ switch (command) {
     await (await import("./commands/undo.ts")).default(commandArgs);
     break;
 
+  case "doctor":
+    await (await import("./commands/doctor.ts")).default(commandArgs);
+    break;
+
+  case "update-prs":
+    await (await import("./commands/update-prs.ts")).default(commandArgs);
+    break;
+
+  case "stacks":
+    await (await import("./commands/stacks.ts")).default(commandArgs);
+    break;
+
   case "archive":
     await (await import("./commands/archive.ts")).default(commandArgs);
     break;
@@ -160,17 +180,22 @@ ${bold("STACK NAVIGATION")}
   ${green("top")}            Jump to the tip of the stack
   ${green("bottom")}         Jump to the base of the stack
   ${green("ls")}             List branches with numbers
+  ${green("stacks")}         List all stacks (--json for tools)
 
 ${bold("STACK MANAGEMENT")}
   ${green("restack")}        Rebase children onto updated parents
   ${green("sync")}           Sync base with main + restack all
   ${green("merge")}          Local squash-merge top-down
+  ${green("split")}          Cut a stack into two at a branch
+  ${green("rename")}         Rename a tracked branch (keeps metadata in sync)
   ${green("delete")}         Remove a branch from the stack
 
 ${bold("INFO & MAINTENANCE")}
   ${green("status")}         PR dashboard (CI, reviews)
   ${green("undo")}           Restore from last snapshot
   ${green("archive")}        Manage archived stacks
+  ${green("update-prs")}     Refresh stack visualization in PR descriptions
+  ${green("doctor")}         Migrate & repair stack metadata
 
 ${bold("GLOBAL OPTIONS")}
   --yes, -y        Skip confirmations ${dim("(for agents/CI)")}

package/src/lib/branch-config.ts

@@ -0,0 +1,132 @@
+// Git-native branch membership index.
+//
+// Each branch records which stack it belongs to (plus its parent and PR) in
+// git's own config under the `branch.<name>` section:
+//
+//   branch.<name>.ghstack-stack   <stack>
+//   branch.<name>.ghstack-parent  <parent-branch>
+//   branch.<name>.ghstack-pr      <number>
+//   branch.<name>.ghstack-id      <uuid>  (stable identity; survives rename)
+//
+// Why config and not JSON: git maintains the `branch.<name>` section for us.
+//   • `git branch -m old new`  → the section moves      → rename tracking free
+//   • `git branch -D name`     → the section is deleted  → no orphaned membership
+//
+// So this is a self-cleaning, rename-safe index that runs alongside the
+// `.gh-stack/` topology files and lets `doctor` cross-check the two. We use
+// dash-separated, all-lowercase variable names on purpose: git only permits
+// alphanumerics and `-` in config keys (underscores are rejected outright),
+// and it lowercases the variable portion on read — so `ghstack-stack` round
+// -trips exactly while a camelCase key would read back mangled.
+import { $ } from "bun";
+
+export interface BranchMembership {
+  stack?: string;
+  parent?: string;
+  pr?: number;
+  id?: string;
+}
+
+const KEY_PREFIX = "ghstack-";
+const STACK_KEY = "ghstack-stack";
+const PARENT_KEY = "ghstack-parent";
+const PR_KEY = "ghstack-pr";
+const ID_KEY = "ghstack-id";
+
+function configKey(branch: string, key: string): string {
+  return `branch.${branch}.${key}`;
+}
+
+/**
+ * Set (or clear) the membership config for a single branch. Any field left
+ * undefined is removed, so callers can pass a full desired state and trust the
+ * branch ends up matching it exactly.
+ */
+export async function setBranchMembership(
+  branch: string,
+  membership: BranchMembership,
+): Promise<void> {
+  await setOrUnset(branch, STACK_KEY, membership.stack);
+  await setOrUnset(branch, PARENT_KEY, membership.parent);
+  await setOrUnset(branch, PR_KEY, membership.pr != null ? String(membership.pr) : undefined);
+  await setOrUnset(branch, ID_KEY, membership.id);
+}
+
+async function setOrUnset(branch: string, key: string, value: string | undefined): Promise<void> {
+  if (value === undefined || value === "") {
+    await unsetKey(branch, key);
+    return;
+  }
+  await $`git config ${configKey(branch, key)} ${value}`.quiet().nothrow();
+}
+
+async function unsetKey(branch: string, key: string): Promise<void> {
+  // `--unset` exits 5 when the key is already absent — harmless, so nothrow.
+  await $`git config --unset ${configKey(branch, key)}`.quiet().nothrow();
+}
+
+/**
+ * Read one branch's membership. Returns an empty object if the branch has no
+ * gh-stack config.
+ */
+export async function getBranchMembership(branch: string): Promise<BranchMembership> {
+  const all = await allBranchMemberships();
+  return all.get(branch) ?? {};
+}
+
+/**
+ * Remove all gh-stack membership keys from a branch (leaves the branch and its
+ * other config untouched).
+ */
+export async function clearBranchMembership(branch: string): Promise<void> {
+  await unsetKey(branch, STACK_KEY);
+  await unsetKey(branch, PARENT_KEY);
+  await unsetKey(branch, PR_KEY);
+  await unsetKey(branch, ID_KEY);
+}
+
+/**
+ * Read every branch's gh-stack membership in one shot, keyed by branch name.
+ *
+ * Branch names may legally contain dots (`feat.x`), so we can't naively split
+ * the config key on `.`. We anchor on the known `.ghstack-<field>` suffix and
+ * treat everything between `branch.` and that suffix as the branch name.
+ */
+export async function allBranchMemberships(): Promise<Map<string, BranchMembership>> {
+  const out = new Map<string, BranchMembership>();
+
+  const { stdout, exitCode } = await $`git config --get-regexp ${"^branch\\..*\\.ghstack-"}`
+    .quiet()
+    .nothrow();
+  // exit 1 simply means no matching keys — an empty repo, not an error.
+  if (exitCode !== 0) return out;
+
+  const text = stdout.toString().trim();
+  if (!text) return out;
+
+  for (const line of text.split("\n")) {
+    const sep = line.indexOf(" ");
+    if (sep === -1) continue;
+    const fullKey = line.slice(0, sep);
+    const value = line.slice(sep + 1);
+
+    // fullKey looks like: branch.<name>.ghstack-<field>
+    if (!fullKey.startsWith("branch.")) continue;
+    const dotField = fullKey.lastIndexOf(`.${KEY_PREFIX}`);
+    if (dotField === -1) continue;
+    const branch = fullKey.slice("branch.".length, dotField);
+    const field = fullKey.slice(dotField + 1); // ghstack-<field>
+
+    const m = out.get(branch) ?? {};
+    if (field === STACK_KEY) m.stack = value;
+    else if (field === PARENT_KEY) m.parent = value;
+    else if (field === ID_KEY) m.id = value;
+    else if (field === PR_KEY) {
+      const n = Number(value);
+      if (Number.isFinite(n)) m.pr = n;
+    }
+    out.set(branch, m);
+  }
+
+  return out;
+}