@node-core/utils 4.0.0

package/bin/ncu-team.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import Request from '../lib/request.js';
+import auth from '../lib/auth.js';
+import { runPromise } from '../lib/run.js';
+import CLI from '../lib/cli.js';
+import TeamInfo from '../lib/team_info.js';
+
+import { setVerbosityFromEnv } from '../lib/verbosity.js';
+
+setVerbosityFromEnv();
+
+yargs(hideBin(process.argv))
+  .completion('completion')
+  .command({
+    command: 'list <team> [org]',
+    desc: 'Get the list of members in a team',
+    builder: (yargs) => {
+      yargs
+        .positional('team', {
+          describe: 'Name of the team',
+          type: 'string'
+        })
+        .positional('org', {
+          describe: 'Name of the organization',
+          type: 'string',
+          default: 'nodejs'
+        });
+    },
+    handler
+  })
+  .command({
+    command: 'sync <file>',
+    desc:
+      'Synchronize the <!-- ncu-team-sync.team($org/$team) --> block in a file',
+    builder: (yargs) => {
+      yargs
+        .positional('file', {
+          describe: 'Path to the file to update',
+          type: 'string'
+        });
+    },
+    handler
+  })
+  .demandCommand(1, 'must provide a valid command')
+  .help()
+  .parse();
+
+function handler(argv) {
+  runPromise(main(argv));
+}
+
+async function main(argv) {
+  const cli = new CLI();
+  const credentials = await auth({
+    github: true
+  });
+  const request = new Request(credentials);
+
+  const [command] = argv._;
+  switch (command) {
+    case 'list': {
+      const info = new TeamInfo(cli, request, argv.org, argv.team);
+      await info.listMembers();
+      break;
+    }
+    case 'sync':
+      await TeamInfo.syncFile(cli, request, argv.file);
+      break;
+    default:
+      throw new Error(`Unknown command ${command}`);
+  }
+}

package/components/git/backport.js

@@ -0,0 +1,70 @@
+import { parsePRFromURL } from '../../lib/links.js';
+import CLI from '../../lib/cli.js';
+import { runPromise } from '../../lib/run.js';
+import BackportSession from '../../lib/backport_session.js';
+
+export const command = 'backport <identifier>';
+export const describe = 'Backport a PR to a release staging branch.';
+
+const epilogue = `====================== Example =======================
+Demo: https://asciinema.org/a/221244
+Backporting https://github.com/nodejs/node/pull/24816 to v11.x
+
+# Sync main with upstream for the commits, if they are not yet there
+$ git checkout main
+$ ncu-config set branch main
+$ git node sync
+
+# Backport existing commits from main to v11.x-staging
+$ git checkout v11.x-staging
+$ ncu-config set branch v11.x-staging
+$ git node sync
+$ git node backport 24816 --to 11
+=====================================================
+`;
+
+let yargsInstance;
+
+export function builder(yargs) {
+  yargsInstance = yargs;
+  return yargs
+    .options({
+      to: {
+        describe: 'release to backport the commits to',
+        type: 'number',
+        required: true
+      }
+    })
+    .positional('identifier', {
+      type: 'string',
+      describe: 'ID or URL of the pull request'
+    })
+    .epilogue(epilogue)
+    .wrap(90);
+}
+
+async function main(argv, parsed) {
+  const merged = (await import('../../lib/config.js')).getMergedConfig();
+  const config = Object.assign({}, argv, parsed, merged);
+  const logStream = process.stdout.isTTY ? process.stdout : process.stderr;
+  const cli = new CLI(logStream);
+  cli.setFigureIndent(0);
+  const dir = process.cwd();
+  const session = new BackportSession(cli, dir, config.prid, config.to);
+  return session.backport();
+}
+
+export function handler(argv) {
+  let parsed = {};
+  const prid = Number.parseInt(argv.identifier);
+  if (!Number.isNaN(prid)) {
+    parsed.prid = prid;
+  } else {
+    parsed = parsePRFromURL(argv.identifier);
+    if (!parsed) {
+      return yargsInstance.showHelp();
+    }
+  }
+
+  return runPromise(main(argv, parsed));
+}

package/components/git/epilogue.js

@@ -0,0 +1,18 @@
+export default `Steps to land a pull request:
+==============================================================================
+$ cd path/to/node/project
+
+# If you have not configured it before
+$ ncu-config set upstream <name-of-remote-to-nodejs/node>
+$ ncu-config set branch main   # Assuming you are landing commits on main
+
+$ git checkout main
+$ git node land --abort          # Abort a landing session, just in case
+$ git node land $PRID            # Start a new landing session
+$ git node land $URL             # Start a new landing session using the PR URL
+
+# Follow instructions provided.
+
+$ git node land --final          # Verify all the commit messages
+==============================================================================
+Watch https://asciinema.org/a/148627 for a complete demo`;

package/components/git/land.js

@@ -0,0 +1,223 @@
+import auth from '../../lib/auth.js';
+import { parsePRFromURL } from '../../lib/links.js';
+import { getMetadata } from '../metadata.js';
+import CLI from '../../lib/cli.js';
+import Request from '../../lib/request.js';
+import { runPromise } from '../../lib/run.js';
+import LandingSession from '../../lib/landing_session.js';
+import epilogue from './epilogue.js';
+
+export const command = 'land [prid|options]';
+export const describe =
+  'Manage the current landing session or start a new one for a pull request';
+
+const landActions = {
+  apply: {
+    describe: 'Apply a patch with the given PR id',
+    type: 'number'
+  },
+  amend: {
+    describe: 'Amend the current commit',
+    type: 'boolean'
+  },
+  continue: {
+    alias: 'c',
+    describe: 'Continue the landing session',
+    type: 'boolean'
+  },
+  final: {
+    describe: 'Verify the landed PR and clean up',
+    type: 'boolean'
+  },
+  abort: {
+    describe: 'Abort the current landing session',
+    type: 'boolean'
+  },
+  backport: {
+    describe: 'Land a backport PR onto a staging branch',
+    default: false,
+    type: 'boolean'
+  },
+  'gpg-sign': {
+    describe: 'GPG-sign commits, will be passed to the git process',
+    alias: 'S'
+  },
+  autorebase: {
+    describe: 'Automatically rebase branches with multiple commits',
+    default: false,
+    type: 'boolean'
+  },
+  fixupAll: {
+    describe: 'Automatically fixup all commits to the first one dismissing ' +
+      'other commit messages',
+    default: false,
+    type: 'boolean'
+  },
+  oneCommitMax: {
+    describe: 'When run in conjunction with the --yes and --autorebase ' +
+      'options, will abort the session if trying to land more than one commit',
+    default: false,
+    type: 'boolean'
+  }
+};
+
+const landOptions = {
+  yes: {
+    type: 'boolean',
+    default: false,
+    describe: 'Assume "yes" as answer to all prompts and run ' +
+    'non-interactively. If an undesirable situation occurs, such as a pull ' +
+    'request or commit check fails, then git node land will abort.'
+  },
+  skipRefs: {
+    describe: 'Prevent adding Fixes and Refs information to commit metadata',
+    default: false,
+    type: 'boolean'
+  },
+  lint: {
+    describe: 'Run linter while landing commits',
+    default: false,
+    type: 'boolean'
+  },
+  checkCI: {
+    describe: 'Query Jenkins CI results when checking the PR',
+    default: true,
+    type: 'boolean'
+  }
+};
+
+let yargsInstance;
+
+export function builder(yargs) {
+  yargsInstance = yargs;
+  return yargs
+    .options(Object.assign({}, landOptions, landActions))
+    .positional('prid', {
+      describe: 'ID or URL of the Pull Request'
+    })
+    .epilogue(epilogue)
+    .example('git node land https://github.com/nodejs/node/pull/12344',
+      'Land https://github.com/nodejs/node/pull/12344 in the current directory')
+    .example('git node land 12344',
+      'Land https://github.com/nodejs/node/pull/12344 in the current directory')
+    .example('git node land --abort',
+      'Abort the current session')
+    .example('git node land --amend',
+      'Append metadata to the current commit message')
+    .example('git node land --final',
+      'Verify the landed PR and clean up')
+    .example('git node land --continue',
+      'Continue the current landing session');
+}
+
+const START = 'start';
+const APPLY = 'apply';
+const AMEND = 'amend';
+const FINAL = 'final';
+const CONTINUE = 'continue';
+const ABORT = 'abort';
+
+export function handler(argv) {
+  if (argv.prid) {
+    if (Number.isInteger(argv.prid)) {
+      return land(START, argv);
+    } else {
+      const parsed = parsePRFromURL(argv.prid);
+      if (parsed) {
+        Object.assign(argv, parsed);
+        return land(START, argv);
+      }
+    }
+    yargsInstance.showHelp();
+    return;
+  }
+
+  const provided = [];
+  for (const type of Object.keys(landActions)) {
+    if (argv[type]) {
+      provided.push(type);
+    }
+  }
+
+  if (provided.length === 1) {
+    return land(provided[0], argv);
+  }
+
+  // If the more than one action is provided or no valid action
+  // is provided, show help.
+  yargsInstance.showHelp();
+}
+
+function land(state, argv) {
+  const cli = new CLI(process.stderr);
+  if (argv.yes) {
+    cli.setAssumeYes();
+  }
+  const dir = process.cwd();
+
+  return runPromise(main(state, argv, cli, dir)).catch((err) => {
+    if (cli.spinner.enabled) {
+      cli.spinner.fail();
+    }
+    throw err;
+  });
+}
+
+async function main(state, argv, cli, dir) {
+  const credentials = await auth({
+    github: true
+  });
+  const req = new Request(credentials);
+  let session = new LandingSession(cli, req, dir);
+
+  if (state !== AMEND &&
+      state !== CONTINUE &&
+      await session.warnForWrongBranch()) {
+    return;
+  }
+
+  if (argv.yes) {
+    cli.setAssumeYes();
+  }
+  try {
+    session.restore();
+  } catch (err) { // JSON error?
+    if (state === ABORT) {
+      await session.abort();
+      return;
+    }
+    cli.warn(
+      'Failed to detect previous session. ' +
+      'please run `git node land --abort`');
+    return;
+  }
+
+  if (state === START) {
+    if (session.hasStarted()) {
+      cli.warn(
+        'Previous `git node land` session for ' +
+        `${session.pullName} in progress.`);
+      cli.log('run `git node land --abort` before starting a new session');
+      return;
+    }
+    session = new LandingSession(cli, req, dir, argv);
+    const metadata = await getMetadata(session.argv, argv.skipRefs, cli);
+    if (argv.backport) {
+      const split = metadata.metadata.split('\n')[0];
+      if (split === 'PR-URL: ') {
+        cli.error('Commit message is missing PR-URL');
+      }
+    }
+    return session.start(metadata);
+  } else if (state === APPLY) {
+    return session.apply();
+  } else if (state === AMEND) {
+    return session.amend();
+  } else if (state === FINAL) {
+    return session.final();
+  } else if (state === ABORT) {
+    return session.abort();
+  } else if (state === CONTINUE) {
+    return session.continue();
+  }
+}

package/components/git/metadata.js

@@ -0,0 +1,94 @@
+import { parsePRFromURL } from '../../lib/links.js';
+import { getMetadata } from '../metadata.js';
+import CLI from '../../lib/cli.js';
+import { getMergedConfig } from '../../lib/config.js';
+import { runPromise, IGNORE } from '../../lib/run.js';
+
+export const command = 'metadata <identifier>';
+export const describe =
+  'Retrieves metadata for a PR and validates them against nodejs/node PR rules';
+
+const config = getMergedConfig();
+
+const options = {
+  owner: {
+    alias: 'o',
+    describe: 'GitHub owner of the PR repository',
+    default: 'nodejs',
+    type: 'string'
+  },
+  repo: {
+    default: 'node',
+    alias: 'r',
+    describe: 'GitHub repository of the PR',
+    type: 'string'
+  },
+  file: {
+    alias: 'f',
+    describe: 'File to write the metadata in',
+    type: 'string'
+  },
+  readme: {
+    describe: 'Path to file that contains collaborator contacts',
+    type: 'string'
+  },
+  'check-comments': {
+    describe: 'Check for \'LGTM\' in comments',
+    type: 'boolean'
+  },
+  'max-commits': {
+    describe: 'Number of commits to warn',
+    type: 'number',
+    default: 3
+  }
+};
+
+let yargsInstance;
+
+export function builder(yargs) {
+  yargsInstance = yargs;
+  return yargs
+    .options(options)
+    .positional('identifier', {
+      type: 'string',
+      describe: 'ID or URL of the pull request'
+    })
+    .example('git node metadata 12344',
+      'Retrieve the metadata of https://github.com/nodejs/node/pull/12344 ' +
+      'and validate the PR')
+    .example('git node metadata https://github.com/nodejs/node/pull/12344',
+      'Retrieve the metadata of https://github.com/nodejs/node/pull/12344 ' +
+      'and validate it')
+    .example('git node metadata 167 --repo llnode --readme ../node/README.md',
+      'Retrieve the metadata of https://github.com/nodejs/llnode/pull/167 ' +
+      'and validate it using the README in ../node/README.md')
+    .wrap(90);
+}
+
+export function handler(argv) {
+  let parsed = {};
+  const prid = Number.parseInt(argv.identifier);
+  if (!Number.isNaN(prid)) {
+    parsed.prid = prid;
+  } else {
+    parsed = parsePRFromURL(argv.identifier);
+    if (!parsed) {
+      return yargsInstance.showHelp();
+    }
+  }
+
+  if (!Number.isInteger(argv.maxCommits) || argv.maxCommits < 0) {
+    return yargsInstance.showHelp();
+  }
+
+  const logStream = process.stdout.isTTY ? process.stdout : process.stderr;
+  const cli = new CLI(logStream);
+
+  const merged = Object.assign({}, argv, parsed, config);
+  return runPromise(getMetadata(merged, false, cli)
+    .then(({ status }) => {
+      if (status === false) {
+        throw new Error(IGNORE);
+      }
+    }));
+}

package/components/git/release.js

@@ -0,0 +1,99 @@
+import CLI from '../../lib/cli.js';
+import ReleasePreparation from '../../lib/prepare_release.js';
+import { runPromise } from '../../lib/run.js';
+
+export const command = 'release [newVersion|options]';
+export const describe = 'Manage an in-progress release or start a new one.';
+
+const PREPARE = 'prepare';
+const PROMOTE = 'promote';
+
+const releaseOptions = {
+  prepare: {
+    describe: 'Prepare a new release of Node.js',
+    type: 'boolean'
+  },
+  promote: {
+    describe: 'Promote new release of Node.js',
+    type: 'boolean'
+  },
+  security: {
+    describe: 'Demarcate the new security release as a security release',
+    type: 'boolean'
+  },
+  filterLabel: {
+    describe: 'Labels separated by "," to filter security PRs',
+    type: 'string'
+  },
+  skipBranchDiff: {
+    describe: 'Skips the initial branch-diff check when preparing releases',
+    type: 'boolean'
+  },
+  startLTS: {
+    describe: 'Mark the release as the transition from Current to LTS',
+    type: 'boolean'
+  }
+};
+
+let yargsInstance;
+
+export function builder(yargs) {
+  yargsInstance = yargs;
+  return yargs
+    .options(releaseOptions).positional('newVersion', {
+      describe: 'Version number of the release to be prepared or promoted'
+    })
+    .example('git node release --prepare 1.2.3',
+      'Prepare a release of Node.js tagged v1.2.3')
+    .example('git node --prepare --startLTS',
+      'Prepare the first LTS release');
+}
+
+export function handler(argv) {
+  if (argv.prepare) {
+    return release(PREPARE, argv);
+  } else if (argv.promote) {
+    return release(PROMOTE, argv);
+  }
+
+  // If more than one action is provided or no valid action
+  // is provided, show help.
+  yargsInstance.showHelp();
+}
+
+function release(state, argv) {
+  const logStream = process.stdout.isTTY ? process.stdout : process.stderr;
+  const cli = new CLI(logStream);
+  const dir = process.cwd();
+
+  return runPromise(main(state, argv, cli, dir)).catch((err) => {
+    if (cli.spinner.enabled) {
+      cli.spinner.fail();
+    }
+    throw err;
+  });
+}
+
+async function main(state, argv, cli, dir) {
+  if (state === PREPARE) {
+    const prep = new ReleasePreparation(argv, cli, dir);
+
+    if (prep.warnForWrongBranch()) return;
+
+    // If the new version was automatically calculated, confirm it.
+    if (!argv.newVersion) {
+      const create = await cli.prompt(
+        `Create release with new version ${prep.newVersion}?`,
+        { defaultAnswer: true });
+
+      if (!create) {
+        cli.error('Aborting release preparation process');
+        return;
+      }
+    }
+
+    return prep.prepare();
+  } else if (state === PROMOTE) {
+    // TODO(codebytere): implement release promotion.
+  }
+}

package/components/git/security.js

@@ -0,0 +1,35 @@
+import CLI from '../../lib/cli.js';
+import SecurityReleaseSteward from '../../lib/prepare_security.js';
+
+export const command = 'security [options]';
+export const describe = 'Manage an in-progress security release or start a new one.';
+
+const securityOptions = {
+  start: {
+    describe: 'Start security release process',
+    type: 'boolean'
+  }
+};
+
+let yargsInstance;
+
+export function builder(yargs) {
+  yargsInstance = yargs;
+  return yargs.options(securityOptions).example(
+    'git node security --start',
+    'Prepare a security release of Node.js');
+}
+
+export function handler(argv) {
+  if (argv.start) {
+    return startSecurityRelease(argv);
+  }
+  yargsInstance.showHelp();
+}
+
+async function startSecurityRelease(argv) {
+  const logStream = process.stdout.isTTY ? process.stdout : process.stderr;
+  const cli = new CLI(logStream);
+  const release = new SecurityReleaseSteward(cli);
+  return release.start();
+}

package/components/git/status.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+import { readJson } from './../../lib/file.js';
+import { getNcuDir } from './../../lib/config.js';
+import CLI from '../../lib/cli.js';
+
+const cli = new CLI();
+
+export const command = 'status';
+export const describe =
+  'Return status and information about the current git-node land session.';
+
+export function handler() {
+  const ncuDir = getNcuDir(process.cwd());
+  const landPath = path.join(ncuDir, 'land');
+
+  if (fs.existsSync(landPath)) {
+    const { state, prid, config } = readJson(landPath);
+    const { username, branch, upstream } = config;
+
+    cli.ok('Landing session in progress');
+    cli.separator();
+    cli.table('PR:', `https:/github.com/nodejs/node/pull/${prid}`);
+    cli.table('State:', state);
+    cli.table('Username:', username);
+    cli.table('Upstream:', upstream);
+    cli.table('Branch:', branch);
+  } else {
+    cli.warn('No landing session in progress');
+  }
+}

package/components/git/sync.js

@@ -0,0 +1,24 @@
+import CLI from '../../lib/cli.js';
+import { runPromise } from '../../lib/run.js';
+import SyncSession from '../../lib/sync_session.js';
+
+export const command = 'sync';
+export const describe = 'Sync the branch specified by ncu-config.';
+
+export function builder(yargs) {
+  return yargs
+    .epilogue('Demo: https://asciinema.org/a/221230')
+    .wrap(90);
+}
+
+async function main() {
+  const logStream = process.stdout.isTTY ? process.stdout : process.stderr;
+  const cli = new CLI(logStream);
+  const dir = process.cwd();
+  const session = new SyncSession(cli, dir);
+  await session.sync();
+}
+
+export function handler(argv) {
+  return runPromise(main());
+}