feat(ng-dev): create pr takeover command

Create a command that allows for a user to checkout and takeover a pull request from github-robot. The process
creates a local copy of the pull request and updates the commit messages to include its merge closing the original
pull request.

Author: josephperrott

ng-dev/BUILD.bazel

@@ -58,6 +58,7 @@ esbuild_esm_bundle(
         # to launch these files/scripts dynamically (through e.g. `spawn` or `fork`).
         "//ng-dev/release/build:build-worker.ts",
         "//ng-dev/pr/merge:strategies/commit-message-filter.ts",
+        "//ng-dev/pr/takeover-pr:commit-message-filter.ts",
     ],
     external = NG_DEV_EXTERNALS,
     splitting = True,

ng-dev/pr/BUILD.bazel

@@ -10,6 +10,7 @@ ts_library(
         "//ng-dev/pr/discover-new-conflicts",
         "//ng-dev/pr/merge",
         "//ng-dev/pr/rebase",
+        "//ng-dev/pr/takeover-pr",
         "@npm//@types/yargs",
     ],
 )

ng-dev/pr/cli.ts

@@ -13,6 +13,7 @@ import {CheckoutCommandModule} from './checkout/cli.js';
 import {DiscoverNewConflictsCommandModule} from './discover-new-conflicts/cli.js';
 import {MergeCommandModule} from './merge/cli.js';
 import {RebaseCommandModule} from './rebase/cli.js';
+import {TakeoverPrCommandModule} from './takeover-pr/cli.js';
 
 /** Build the parser for pull request commands. */
 export function buildPrParser(localYargs: Argv) {
@@ -24,5 +25,6 @@ export function buildPrParser(localYargs: Argv) {
     .command(RebaseCommandModule)
     .command(MergeCommandModule)
     .command(CheckoutCommandModule)
+    .command(TakeoverPrCommandModule)
     .command(CheckTargetBranchesModule);
 }

ng-dev/pr/takeover-pr/BUILD.bazel

@@ -0,0 +1,18 @@
+load("//tools:defaults.bzl", "ts_library")
+
+exports_files([
+    "commit-message-filter.ts",
+])
+
+ts_library(
+    name = "takeover-pr",
+    srcs = glob(["*.ts"]),
+    visibility = ["//ng-dev:__subpackages__"],
+    deps = [
+        "//ng-dev/pr/common",
+        "//ng-dev/pr/merge",
+        "//ng-dev/utils",
+        "@npm//@types/node",
+        "@npm//@types/yargs",
+    ],
+)

ng-dev/pr/takeover-pr/cli.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright Google LLC
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Argv, Arguments, CommandModule} from 'yargs';
+
+import {addGithubTokenOption} from '../../utils/git/github-yargs.js';
+import {takeoverPullRequest} from './takeover-pr.js';
+
+export interface CheckoutOptions {
+  pr: number;
+  branch?: string;
+}
+
+/** Builds the checkout pull request command. */
+function builder(yargs: Argv) {
+  return addGithubTokenOption(yargs)
+    .positional('pr', {type: 'number', demandOption: true})
+    .option('branch', {
+      type: 'string',
+      describe: 'An optional branch name to use instead of a pull request number based name',
+      demandOption: false,
+    });
+}
+
+/** Handles the checkout pull request command. */
+async function handler(options: Arguments<CheckoutOptions>) {
+  await takeoverPullRequest(options);
+}
+
+/** yargs command module for checking out a PR  */
+export const TakeoverPrCommandModule: CommandModule<{}, CheckoutOptions> = {
+  handler,
+  builder,
+  command: 'takeover <pr>',
+  describe: 'Takeover a pull request from a stale upstream pull request',
+};

ng-dev/pr/takeover-pr/commit-message-filter.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright Google LLC
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+/**
+ * Script that can be passed as commit message filter to `git filter-branch --msg-filter`.
+ * The script rewrites commit messages to contain a Github instruction to close the
+ * corresponding pull request. For more details. See: https://git.io/Jv64r.
+ */
+
+main();
+
+function main() {
+  const [prNumber] = process.argv.slice(2);
+  if (!prNumber) {
+    console.error('No pull request number specified.');
+    process.exit(1);
+  }
+
+  let commitMessage = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    const chunk = process.stdin.read();
+    if (chunk !== null) {
+      commitMessage += chunk;
+    }
+  });
+
+  process.stdin.on('end', () => {
+    console.info(rewriteCommitMessage(commitMessage, prNumber));
+  });
+}
+
+function rewriteCommitMessage(message: string, prNumber: string) {
+  const lines = message.split(/\n/);
+  lines.push(`Closes #${prNumber} as this was created using the \`ng-dev pr takeover\` tooling`);
+  return lines.join('\n');
+}

ng-dev/pr/takeover-pr/takeover-pr.ts

@@ -0,0 +1,72 @@
+import {dirname, join} from 'path';
+import {AuthenticatedGitClient} from '../../utils/git/authenticated-git-client.js';
+import {Log, bold, green} from '../../utils/logging.js';
+import {checkOutPullRequestLocally} from '../common/checkout-pr.js';
+import {fileURLToPath} from 'url';
+
+/** List of accounts that are supported for takeover. */
+const takeoverAccounts = ['angular-robot'];
+
+export async function takeoverPullRequest({
+  pr,
+  branch,
+}: {
+  pr: number;
+  branch?: string;
+}): Promise<void> {
+  /** An authenticated git client. */
+  const git = await AuthenticatedGitClient.get();
+  /** The branch name used for the takeover change. */
+  const branchName = branch ?? `pr-${pr}`;
+
+  // Make sure the local repository is clean.
+  if (git.hasUncommittedChanges()) {
+    Log.error(
+      ` ✘ Local working repository not clean. Please make sure there are no uncommitted changes`,
+    );
+    return;
+  }
+
+  // Verify that the expected branch name is available.
+  if (git.runGraceful(['rev-parse', '-q', '--verify', branchName]).status === 0) {
+    Log.error(` ✘ Expected branch name \`${branchName}\` already in use`);
+    return;
+  }
+
+  /** The pull request information from Github. */
+  const {data: pullRequest} = await git.github.pulls.get({pull_number: pr, ...git.remoteParams});
+
+  // Confirm that the takeover request is being done on a valid pull request.
+  if (!takeoverAccounts.includes(pullRequest.user.login)) {
+    Log.error(` ✘ Unable to takeover pull request from: ${bold(pullRequest.user.login)}`);
+    Log.error(`   Supported accounts: ${bold(takeoverAccounts.join(', '))}`);
+    return;
+  }
+
+  Log.info(`Checking out \`${pullRequest.head.label}\` locally`);
+  await checkOutPullRequestLocally(pr, {allowIfMaintainerCannotModify: true});
+
+  Log.info(`Setting local branch name based on the pull request`);
+  git.run(['checkout', '-q', '-b', branchName]);
+
+  Log.info('Updating commit messages to close previous pull request');
+  git.run([
+    'filter-branch',
+    '-f',
+    '--msg-filter',
+    `${getCommitMessageFilterScriptPath()} ${pr}`,
+    `${pullRequest.base.sha}..HEAD`,
+  ]);
+
+  Log.info(` ${green('✔')} Checked out pull request #${pr} into branch: ${branchName}`);
+}
+
+/** Gets the absolute file path to the commit-message filter script. */
+function getCommitMessageFilterScriptPath(): string {
+  // This file is getting bundled and ends up in `<pkg-root>/bundles/<chunk>`. We also
+  // bundle the commit-message-filter script as another entry-point and can reference
+  // it relatively as the path is preserved inside `bundles/`.
+  // *Note*: Relying on package resolution is problematic within ESM and with `local-dev.sh`
+  const bundlesDir = dirname(fileURLToPath(import.meta.url));
+  return join(bundlesDir, './pr/takeover-pr/commit-message-filter.mjs');
+}