gh-stack 0.17.2 → 0.19.0

package/src/lib/collapse-guard.ts

@@ -0,0 +1,325 @@
+// After `merge` collapses a stack top-down on GitHub (PR3 squashed into PR2's
+// branch, PR2 into PR1's), every child's content lives in one squash commit on
+// its parent's branch. If that branch is rewritten before the base PR merges
+// (#28: a sync rebased the base and force-pushed it without the squash commit),
+// the base PR ships without its children, and nothing errors.
+//
+// So before the base PR is handed to main, check that each child's squash
+// commit is still in what it was squashed into:
+//   - a child of the base: the base branch's head on origin;
+//   - a child of an intermediate branch: that branch's PR head when it merged
+//     (what was squashed into *its* parent).
+//
+// Fail closed. "covered" needs proof: the commit is an ancestor, a commit
+// there has its patch-id, or the tree holds every file it wrote at the blob it
+// wrote. "missing" needs proof too: the tree holds every file it touched
+// exactly as it was *before* the commit. Anything in between is "unconfirmed",
+// and a lookup that fails is "unverified". The caller must not merge on either
+// without asking (and never under --yes).
+import { $ } from "bun";
+import * as git from "./git.ts";
+import type { PrMergeResult } from "./github.ts";
+
+export interface CollapsedChild {
+  branch: string;
+  pr: number;
+  /** The stack parent it was squashed into. */
+  parent: string;
+  /** The parent's PR, when the parent isn't the base. */
+  parentPr: number | null;
+}
+
+/**
+ * A file a commit touched: its path, GitHub's status, its blob after the
+ * commit (null if removed), and, when known, its blob before (null if added).
+ */
+export interface CommitFile {
+  filename: string;
+  status: string;
+  sha: string | null;
+  before?: string | null;
+}
+
+/** GitHub lookups, injected so the check runs against a local remote in tests. */
+export interface CollapseLookup {
+  prResult(
+    pr: number,
+  ): Promise<Pick<PrMergeResult, "state" | "baseRefName" | "headRefOid" | "mergeCommit"> | null>;
+  commitPatch(sha: string): Promise<string | null>;
+  /** The files a commit changed; null if unavailable or truncated. */
+  commitFiles(sha: string): Promise<CommitFile[] | null>;
+}
+
+interface Placement {
+  mergeCommit: string;
+  /** The commit that should contain it, and what that is ("origin/pr1", "PR #2's merged head"). */
+  container: string;
+  containerLabel: string;
+}
+
+export type CollapseVerdict =
+  | { child: CollapsedChild; status: "covered" }
+  /** Proven absent: every file it touched is still as it was before it. */
+  | ({ child: CollapsedChild; status: "missing"; fetchable: boolean } & Placement)
+  /** Compared, but neither proof held: maybe there, maybe not. */
+  | ({
+      child: CollapsedChild;
+      status: "unconfirmed";
+      reason: string;
+      transient: boolean;
+    } & Placement)
+  /** Couldn't get far enough to compare. */
+  | { child: CollapsedChild; status: "unverified"; reason: string; transient: boolean };
+
+export async function verifyCollapse(opts: {
+  base: string;
+  trunkRef: string;
+  children: CollapsedChild[];
+  lookup: CollapseLookup;
+}): Promise<CollapseVerdict[]> {
+  const { base, trunkRef, children, lookup } = opts;
+  const shallow =
+    (await $`git rev-parse --is-shallow-repository`.nothrow().quiet()).stdout.toString().trim() ===
+    "true";
+
+  // GitHub lookups: each PR once (a parent is also a child), all at once.
+  const prs = new Map<number, ReturnType<CollapseLookup["prResult"]>>();
+  const pr = (n: number) => {
+    if (!prs.has(n))
+      prs.set(
+        n,
+        lookup.prResult(n).catch(() => null),
+      );
+    return prs.get(n)!;
+  };
+  await Promise.all(
+    children.flatMap((c) => [pr(c.pr), ...(c.parentPr != null ? [pr(c.parentPr)] : [])]),
+  );
+
+  const heads = await git.remoteHeads();
+  const baseTip = heads.get(base) ?? null;
+  if (baseTip) await git.fetchObjectsOnly([`refs/heads/${base}`]);
+
+  // The git side runs one child at a time: concurrent fetches into one
+  // repository contend for the same pack and ref locks.
+  const verdicts: CollapseVerdict[] = [];
+  for (const child of children) {
+    const result = await pr(child.pr);
+    if (!result) {
+      verdicts.push({
+        child,
+        status: "unverified",
+        reason: `couldn't read PR #${child.pr} from GitHub`,
+        transient: true,
+      });
+      continue;
+    }
+    if (result.state !== "MERGED" || !result.mergeCommit) {
+      verdicts.push({
+        child,
+        status: "unverified",
+        reason: "GitHub reports no merge commit for it",
+        transient: false,
+      });
+      continue;
+    }
+    if (result.baseRefName !== child.parent) {
+      verdicts.push({
+        child,
+        status: "unverified",
+        reason: `it merged into ${result.baseRefName}, not ${child.parent}`,
+        transient: false,
+      });
+      continue;
+    }
+
+    // What should contain the squash commit.
+    let container: string | null;
+    let containerLabel: string;
+    if (child.parent === base) {
+      container = baseTip;
+      containerLabel = `origin/${base}`;
+    } else {
+      const parentResult = child.parentPr != null ? await pr(child.parentPr) : null;
+      const merged = parentResult?.state === "MERGED";
+      container = merged ? parentResult.headRefOid : (heads.get(child.parent) ?? null);
+      containerLabel = merged ? `PR #${child.parentPr}'s merged head` : `origin/${child.parent}`;
+      if (container && !(await hasCommit(container))) await git.fetchObjectsOnly([container]);
+    }
+    if (!container || !(await hasCommit(container))) {
+      verdicts.push({
+        child,
+        status: "unverified",
+        reason: `couldn't fetch ${containerLabel}`,
+        transient: true,
+      });
+      continue;
+    }
+
+    const squash = result.mergeCommit;
+    const placement = { mergeCommit: squash, container, containerLabel };
+    if (!(await hasCommit(squash))) await git.fetchObjectsOnly([squash]);
+    const fetchable = await hasCommit(squash);
+
+    // The commit and its patch from our own objects when we have them,
+    // otherwise from GitHub (an orphaned squash commit usually can't be fetched).
+    let patchId: string | null;
+    let files: CommitFile[] | null;
+    let historyChecked = false;
+    if (fetchable) {
+      if (await git.isAncestor(squash, container)) {
+        verdicts.push({ child, status: "covered" });
+        continue;
+      }
+      patchId = await patchIdOf(squash);
+      files = await localCommitFiles(squash);
+      historyChecked = !shallow;
+    } else {
+      const patch = await lookup.commitPatch(squash).catch(() => null);
+      patchId = patch === null ? null : await patchIdFromText(patch);
+      files = await lookup.commitFiles(squash).catch(() => null);
+      // Fetching the container brought all its ancestors, so in a full clone
+      // a squash commit we still don't have isn't one of them.
+      historyChecked = !shallow;
+    }
+
+    if ((await patchIdIn(patchId, container, trunkRef)) || (await filesIn(files, container))) {
+      verdicts.push({ child, status: "covered" });
+      continue;
+    }
+    if (await filesAsBefore(files, container)) {
+      verdicts.push({ child, status: "missing", fetchable, ...placement });
+      continue;
+    }
+
+    const gaps: string[] = [];
+    if (!historyChecked) {
+      gaps.push(
+        "the repository is shallow, so its history couldn't be searched (git fetch --unshallow)",
+      );
+    }
+    if (patchId === null) gaps.push("its patch couldn't be read");
+    if (files === null) gaps.push("its file list couldn't be read");
+    if (files !== null) {
+      gaps.push(
+        "its files there match neither its own version nor the one before it (they may have changed since)",
+      );
+    }
+    verdicts.push({
+      child,
+      status: "unconfirmed",
+      reason: gaps.join("; "),
+      // A GitHub read that failed may succeed on a retry.
+      transient: !fetchable && (patchId === null || files === null),
+      ...placement,
+    });
+  }
+  return verdicts;
+}
+
+async function hasCommit(sha: string): Promise<boolean> {
+  return git.refExists(`${sha}^{commit}`);
+}
+
+async function patchIdOf(sha: string): Promise<string | null> {
+  const { stdout } = await $`git show ${sha} | git patch-id --stable`.nothrow().quiet();
+  return stdout.toString().trim().split(" ")[0] || null;
+}
+
+async function patchIdFromText(patch: string): Promise<string | null> {
+  const { stdout } = await $`git patch-id --stable < ${new Response(patch)}`.nothrow().quiet();
+  return stdout.toString().trim().split(" ")[0] || null;
+}
+
+/** Whether a commit with this patch-id is among `container`'s own commits (above the trunk). */
+async function patchIdIn(id: string | null, container: string, trunkRef: string): Promise<boolean> {
+  if (!id) return false;
+  const exclude = (await git.refExists(trunkRef)) ? [`^${trunkRef}`] : [];
+  const { stdout } =
+    await $`git log -p --no-merges --max-count=2000 ${container} ${exclude} | git patch-id --stable`
+      .nothrow()
+      .quiet();
+  return stdout
+    .toString()
+    .split("\n")
+    .some((line) => line.split(" ")[0] === id);
+}
+
+const NO_BLOB = /^0+$/;
+
+/**
+ * The files a local commit touched, with blobs before and after. NUL-separated
+ * (-z) so paths come back raw, exactly as GitHub's API reports them.
+ */
+export async function localCommitFiles(sha: string): Promise<CommitFile[] | null> {
+  const { stdout, exitCode } = await $`git diff-tree -r -z --no-commit-id --root ${sha}`
+    .nothrow()
+    .quiet();
+  if (exitCode !== 0) return null;
+  // -z: ":<old mode> <new mode> <old blob> <new blob> <status>\0<path>\0" per file.
+  const parts = stdout.toString().split("\0");
+  const files: CommitFile[] = [];
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    const meta = parts[i]!.replace(/^:/, "").split(" ");
+    const [, , oldBlob, newBlob, status] = meta;
+    if (!status) continue;
+    files.push({
+      filename: parts[i + 1]!,
+      status: status === "A" ? "added" : status === "D" ? "removed" : "modified",
+      sha: NO_BLOB.test(newBlob!) ? null : newBlob!,
+      before: NO_BLOB.test(oldBlob!) ? null : oldBlob!,
+    });
+  }
+  return files;
+}
+
+/** Each path's blob in `tree` (absent paths are missing from the map). */
+async function blobsAt(tree: string, paths: string[]): Promise<Map<string, string> | null> {
+  const { stdout, exitCode } = await $`git --literal-pathspecs ls-tree -r -z ${tree} -- ${paths}`
+    .nothrow()
+    .quiet();
+  if (exitCode !== 0) return null;
+  const blobs = new Map<string, string>();
+  for (const entry of stdout.toString().split("\0").filter(Boolean)) {
+    // "<mode> <type> <blob>\t<path>"
+    const tab = entry.indexOf("\t");
+    blobs.set(entry.slice(tab + 1), entry.slice(0, tab).split(" ")[2]!);
+  }
+  return blobs;
+}
+
+/**
+ * Whether `container` holds every file `files` wrote, at the blob it wrote
+ * (and none it removed): the content is there even if the commit was
+ * rewritten. False when unsure, which never by itself means missing.
+ */
+async function filesIn(files: CommitFile[] | null, container: string): Promise<boolean> {
+  if (!files || files.length === 0) return false;
+  const blobs = await blobsAt(
+    container,
+    files.map((f) => f.filename),
+  );
+  if (!blobs) return false;
+  return files.every((f) =>
+    f.status === "removed"
+      ? !blobs.has(f.filename)
+      : f.sha !== null && blobs.get(f.filename) === f.sha,
+  );
+}
+
+/**
+ * Whether `container` holds every file `files` touched exactly as it was
+ * *before* the commit: positive evidence its changes aren't there. Needs the
+ * "before" of every file (GitHub's API only gives that for added files).
+ */
+async function filesAsBefore(files: CommitFile[] | null, container: string): Promise<boolean> {
+  if (!files || files.length === 0 || files.some((f) => f.before === undefined)) return false;
+  const blobs = await blobsAt(
+    container,
+    files.map((f) => f.filename),
+  );
+  if (!blobs) return false;
+  return files.every((f) =>
+    f.before === null ? !blobs.has(f.filename) : blobs.get(f.filename) === f.before,
+  );
+}

package/src/lib/config.ts

@@ -0,0 +1,259 @@
+// Defaults config (#39): repo and user defaults for boolean command flags, so
+// a convention like "every PR opens as a draft" can't be forgotten.
+//
+//   .gh-stack.toml at the repo root          (committed, shared by the team)
+//   ~/.config/gh-stack/config.toml           (personal; honors XDG_CONFIG_HOME)
+//   GH_STACK_DRAFT=1, GH_STACK_NO_PUSH=1     (env, per session)
+//
+// Precedence, highest first: CLI flag > env > repo config > user config > built-in.
+// Keys mirror command and flag names (`[submit] draft`). A new default is one
+// entry in SETTINGS. `--yes` is deliberately not configurable from any file.
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { repoRoot } from "./git.ts";
+
+export type ConfigSource = "flag" | "env" | "repo" | "user" | "default";
+
+export interface BoolSetting {
+  section: string;
+  key: string;
+  builtin: boolean;
+  /** Flags that turn it on / off. The last one on the command line wins. */
+  onFlags: string[];
+  offFlags: string[];
+  /** `invert`: the variable names the opposite (GH_STACK_NO_PUSH=1 → push = false). */
+  env: { name: string; invert?: boolean };
+  description: string;
+}
+
+export const SETTINGS = {
+  "submit.draft": {
+    section: "submit",
+    key: "draft",
+    builtin: false,
+    onFlags: ["--draft", "-d"],
+    offFlags: ["--no-draft"],
+    env: { name: "GH_STACK_DRAFT" },
+    description: "Create new PRs as drafts",
+  },
+  "restack.push": {
+    section: "restack",
+    key: "push",
+    builtin: true,
+    onFlags: ["--push"],
+    offFlags: ["--no-push"],
+    env: { name: "GH_STACK_NO_PUSH", invert: true },
+    description: "Push rebased branches (restack and sync)",
+  },
+} satisfies Record<string, BoolSetting>;
+
+export type SettingName = keyof typeof SETTINGS;
+
+export const REPO_CONFIG_FILE = ".gh-stack.toml";
+
+export interface ConfigFile {
+  path: string;
+  exists: boolean;
+  data: Record<string, unknown>;
+}
+
+export interface ConfigLayers {
+  env: Record<string, string | undefined>;
+  repo: ConfigFile | null;
+  user: ConfigFile | null;
+}
+
+export interface Resolved {
+  value: boolean;
+  source: ConfigSource;
+  /** The flag, env var, or file the value came from. */
+  origin?: string;
+}
+
+/** A config problem the user must fix: malformed TOML, a wrong-typed value. */
+export class ConfigError extends Error {}
+
+function settingByPath(section: string, key: string): BoolSetting | undefined {
+  return (SETTINGS as Record<string, BoolSetting>)[`${section}.${key}`];
+}
+
+/**
+ * Parse a flag-default env var: 1/true/yes or 0/false/no (any case); empty =
+ * unset. Anything else is an error, so a typo can't be silently ignored.
+ */
+export function parseEnvBool(name: string, raw: string | undefined): boolean | undefined {
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const v = raw.trim().toLowerCase();
+  if (["1", "true", "yes"].includes(v)) return true;
+  if (["0", "false", "no"].includes(v)) return false;
+  throw new ConfigError(`${name}=${raw} is not a boolean (use 1/0, true/false, or yes/no).`);
+}
+
+/**
+ * Check a parsed config file against SETTINGS. A known key with a non-boolean
+ * value is an error (silently falling back could open a PR the repo wanted as
+ * a draft); unknown sections and keys come back as warnings.
+ */
+export function validateConfig(data: Record<string, unknown>, file: string): string[] {
+  const warnings: string[] = [];
+  for (const [section, value] of Object.entries(data)) {
+    if (section === "yes") {
+      warnings.push(yesWarning(section, file));
+      continue;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      warnings.push(`ignoring unknown key "${section}" in ${file}`);
+      continue;
+    }
+    for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+      const spec = settingByPath(section, key);
+      if (!spec) {
+        warnings.push(
+          key === "yes"
+            ? yesWarning(`[${section}] yes`, file)
+            : `ignoring unknown key [${section}] ${key} in ${file}`,
+        );
+        continue;
+      }
+      if (typeof v !== "boolean") {
+        throw new ConfigError(
+          `[${section}] ${key} in ${file} must be true or false, got ${JSON.stringify(v)}.`,
+        );
+      }
+    }
+  }
+  return warnings;
+}
+
+function yesWarning(where: string, file: string): string {
+  return (
+    `ignoring ${where} in ${file}: auto-confirming destructive operations can't be ` +
+    `set in a config file. Pass --yes or set GH_STACK_YES=1 for the run that needs it.`
+  );
+}
+
+/** The value an explicit flag sets, or null when no flag for it is present. */
+export function flagSetting(name: SettingName, args: string[]): Resolved | null {
+  const spec: BoolSetting = SETTINGS[name];
+  for (let i = args.length - 1; i >= 0; i--) {
+    const arg = args[i]!;
+    if (spec.onFlags.includes(arg)) return { value: true, source: "flag", origin: arg };
+    if (spec.offFlags.includes(arg)) return { value: false, source: "flag", origin: arg };
+  }
+  return null;
+}
+
+/**
+ * Resolve one setting from the CLI args and the config layers. Pure: the
+ * layers are loaded (and validated) by `loadConfigLayers`.
+ */
+export function resolveSetting(name: SettingName, args: string[], layers: ConfigLayers): Resolved {
+  const spec: BoolSetting = SETTINGS[name];
+
+  const flag = flagSetting(name, args);
+  if (flag) return flag;
+
+  const envValue = parseEnvBool(spec.env.name, layers.env[spec.env.name]);
+  if (envValue !== undefined) {
+    return {
+      value: spec.env.invert ? !envValue : envValue,
+      source: "env",
+      origin: spec.env.name,
+    };
+  }
+
+  for (const source of ["repo", "user"] as const) {
+    const file = layers[source];
+    const section = file?.data[spec.section] as Record<string, unknown> | undefined;
+    const v = section?.[spec.key];
+    if (typeof v === "boolean") return { value: v, source, origin: file!.path };
+  }
+
+  return { value: spec.builtin, source: "default" };
+}
+
+/**
+ * Read and validate one TOML file. A missing file (ENOENT) is an empty layer;
+ * any other read failure (a directory, no permission) is a ConfigError.
+ */
+export function loadConfigFile(file: string): { file: ConfigFile; warnings: string[] } {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { file: { path: file, exists: false, data: {} }, warnings: [] };
+    }
+    throw new ConfigError(`can't read ${file}: ${(err as Error).message}`);
+  }
+  let data: Record<string, unknown>;
+  try {
+    data = Bun.TOML.parse(text) as Record<string, unknown>;
+  } catch (err) {
+    throw new ConfigError(`invalid TOML in ${file}: ${(err as Error).message}`);
+  }
+  return { file: { path: file, exists: true, data }, warnings: validateConfig(data, file) };
+}
+
+/** `$XDG_CONFIG_HOME/gh-stack/config.toml`, else `~/.config/gh-stack/config.toml`. */
+export function userConfigPath(env: Record<string, string | undefined> = process.env): string {
+  const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "gh-stack", "config.toml");
+}
+
+/** `<repo root>/.gh-stack.toml`, or null outside a work tree. */
+export async function repoConfigPath(): Promise<string | null> {
+  try {
+    const root = await repoRoot();
+    return root ? path.join(root, REPO_CONFIG_FILE) : null;
+  } catch {
+    return null; // not in a git work tree (e.g. `gh-stack config` run anywhere)
+  }
+}
+
+/**
+ * Load env + repo + user layers. Files are re-read on every call (they're tiny
+ * and commands resolve once or twice), so in-process tests that switch repos
+ * never see a stale layer. Throws ConfigError; returns warnings to print.
+ */
+export async function loadConfigLayers(): Promise<{ layers: ConfigLayers; warnings: string[] }> {
+  const repoPath = await repoConfigPath();
+  const repo = repoPath ? loadConfigFile(repoPath) : null;
+  const user = loadConfigFile(userConfigPath());
+  return {
+    layers: { env: process.env, repo: repo?.file ?? null, user: user.file },
+    warnings: [...(repo?.warnings ?? []), ...user.warnings],
+  };
+}
+
+/**
+ * Resolve a setting for a command. An explicit flag decides without reading
+ * any config, so a broken config file or env var can't stop a command (or a
+ * chained one, like merge's restack) that was told exactly what to do.
+ * Otherwise the layers are loaded: warnings go to stderr, and a ConfigError
+ * is thrown for the command, or index.ts, to report.
+ */
+export async function resolveFlag(name: SettingName, args: string[]): Promise<Resolved> {
+  const flag = flagSetting(name, args);
+  if (flag) return flag;
+  const { layers, warnings } = await loadConfigLayers();
+  for (const w of warnings) console.error(`gh-stack: warning: ${w}`);
+  return resolveSetting(name, [], layers);
+}
+
+/** Human-readable origin of a resolved value, e.g. `repo config (/x/.gh-stack.toml)`. */
+export function describeSource(r: Resolved): string {
+  switch (r.source) {
+    case "flag":
+      return `${r.origin} flag`;
+    case "env":
+      return `${r.origin} env var`;
+    case "repo":
+      return `repo config (${r.origin})`;
+    case "user":
+      return `user config (${r.origin})`;
+    case "default":
+      return "built-in default";
+  }
+}