Add flow for monorepo w/ independent versions (#6)

This commit introduces a rough cut of a flow which supports a monorepo
with an independent versioning strategy. This flow:

* Generates a "release specification" file containing all of the
  workspace packages within the repo (this will be changed to all
  _updated_ packages in a future commit)
* Opens the user's editor (if one can is detected) and waits for them to
  edit it
* Parses the edited version of the release spec
* Applies the release spec by:
  * Updating the version of the root package with the current date
    (note: the format of the version string will be changed in a future
    commit)
  * Updating the versions of all of the packages listed in the release
    spec
  * Adds new sections to the changelogs of all of the packages listed in
    the release spec

In addition:

* Bump dev version of Node to v16

Author: mcmire

.eslintrc.js

@@ -29,13 +29,8 @@ module.exports = {
         next: 'multiline-block-like',
       },
     ],
-    // This prevents using bulleted/numbered lists in JSDoc blocks.
-    // See: <https://github.com/gajus/eslint-plugin-jsdoc/issues/541>
-    'jsdoc/check-indentation': 'off',
     // It's common for scripts to access `process.env`
     'node/no-process-env': 'off',
-    // It's common for scripts to exit explicitly
-    'node/no-process-exit': 'off',
   },
 
   overrides: [

.nvmrc

@@ -1 +1 @@
-v14
+v16

README.md

@@ -24,8 +24,9 @@ For more on how to use this tool, please see the [docs](./docs).
 
 ### Setup
 
-- Install [Node.js](https://nodejs.org) version 12
+- Install [Node.js](https://nodejs.org) version 16
   - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you.
+  - Note that the version of Node used for development (in `.nvmrc`) is intentionally higher than version used for consumption (as `engines` in `package.json`), as we have not fully phased out legacy versions of Node from our products yet.
 - Install [Yarn v3](https://yarnpkg.com/getting-started/install)
 - Run `yarn install` to install dependencies and run any required post-install scripts
 

jest.config.js

@@ -28,9 +28,11 @@ module.exports = {
   coverageDirectory: 'coverage',
 
   // An array of regexp pattern strings used to skip coverage collection
-  // coveragePathIgnorePatterns: [
-  //   "/node_modules/"
-  // ],
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '/src/cli.ts',
+    '/src/command-line-arguments.ts',
+  ],
 
   // Indicates which provider should be used to instrument code for coverage
   coverageProvider: 'babel',
@@ -135,7 +137,7 @@ module.exports = {
   // setupFiles: [],
 
   // A list of paths to modules that run some code to configure or set up the testing framework before each test
-  // setupFilesAfterEnv: [],
+  setupFilesAfterEnv: ['./tests/setupAfterEnv.ts'],
 
   // The number of seconds after which a test is considered as slow and reported as such in the results.
   // slowTestThreshold: 5,

package.json

@@ -6,8 +6,7 @@
     "type": "git",
     "url": "https://github.com/MetaMask/create-release-branch.git"
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "bin": "dist/cli.js",
   "files": [
     "dist/"
   ],
@@ -18,19 +17,36 @@
     "lint:eslint": "eslint . --cache --ext js,ts",
     "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write",
     "lint:misc": "prettier '**/*.json' '**/*.md' '!CHANGELOG.md' '**/*.yml' '!.yarnrc.yml' --ignore-path .gitignore --no-error-on-unmatched-pattern",
-    "prepack": "yarn build",
+    "prepack": "yarn build:clean && chmod +x dist/cli.js && yarn lint && yarn test",
     "test": "jest && jest-it-up",
     "test:watch": "jest --watch"
   },
+  "dependencies": {
+    "@metamask/action-utils": "^0.0.2",
+    "@metamask/utils": "^2.0.0",
+    "debug": "^4.3.4",
+    "execa": "^5.0.0",
+    "glob": "^8.0.3",
+    "pony-cause": "^2.1.0",
+    "semver": "^7.3.7",
+    "which": "^2.0.2",
+    "yaml": "^2.1.1",
+    "yargs": "^17.5.1"
+  },
   "devDependencies": {
     "@lavamoat/allow-scripts": "^2.0.3",
     "@metamask/auto-changelog": "^2.3.0",
     "@metamask/eslint-config": "^9.0.0",
     "@metamask/eslint-config-jest": "^9.0.0",
     "@metamask/eslint-config-nodejs": "^9.0.0",
     "@metamask/eslint-config-typescript": "^9.0.1",
+    "@types/debug": "^4.1.7",
     "@types/jest": "^28.1.4",
+    "@types/jest-when": "^3.5.2",
     "@types/node": "^17.0.23",
+    "@types/rimraf": "^3.0.2",
+    "@types/which": "^2.0.1",
+    "@types/yargs": "^17.0.10",
     "@typescript-eslint/eslint-plugin": "^4.21.0",
     "@typescript-eslint/parser": "^4.21.0",
     "eslint": "^7.23.0",
@@ -42,9 +58,12 @@
     "eslint-plugin-prettier": "^3.3.1",
     "jest": "^28.0.0",
     "jest-it-up": "^2.0.2",
+    "jest-when": "^3.5.1",
+    "nanoid": "^3.3.4",
     "prettier": "^2.2.1",
     "prettier-plugin-packagejson": "^2.2.17",
     "rimraf": "^3.0.2",
+    "stdio-mock": "^1.2.0",
     "ts-jest": "^28.0.0",
     "ts-node": "^10.7.0",
     "typescript": "^4.2.4"

src/cli.ts

@@ -0,0 +1,18 @@
+import { main } from './main';
+
+/**
+ * The entrypoint to this tool.
+ */
+async function cli() {
+  await main({
+    argv: process.argv,
+    cwd: process.cwd(),
+    stdout: process.stdout,
+    stderr: process.stderr,
+  });
+}
+
+cli().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

src/command-line-arguments.ts

@@ -0,0 +1,43 @@
+import yargs from 'yargs/yargs';
+import { hideBin } from 'yargs/helpers';
+
+export interface CommandLineArguments {
+  projectDirectory: string;
+  tempDirectory: string | undefined;
+  reset: boolean;
+}
+
+/**
+ * Parses the arguments provided on the command line using `yargs`.
+ *
+ * @param argv - The name of this executable and its arguments (as obtained via
+ * `process.argv`).
+ * @returns A promise for the `yargs` arguments object.
+ */
+export async function readCommandLineArguments(
+  argv: string[],
+): Promise<CommandLineArguments> {
+  return await yargs(hideBin(argv))
+    .usage(
+      'This tool prepares your project for a new release by bumping versions and updating changelogs.',
+    )
+    .option('project-directory', {
+      alias: 'd',
+      describe: 'The directory that holds your project.',
+      default: '.',
+    })
+    .option('temp-directory', {
+      describe:
+        'The directory that is used to hold temporary files, such as the release spec template.',
+      type: 'string',
+    })
+    .option('reset', {
+      describe:
+        'Removes any cached files from a previous run that may have been created.',
+      type: 'boolean',
+      default: false,
+    })
+    .help()
+    .strict()
+    .parse();
+}

src/editor.test.ts

@@ -0,0 +1,115 @@
+import { when } from 'jest-when';
+import { determineEditor } from './editor';
+import * as envModule from './env';
+import * as miscUtils from './misc-utils';
+
+jest.mock('./env');
+jest.mock('./misc-utils');
+
+describe('editor', () => {
+  describe('determineEditor', () => {
+    it('returns information about the editor from EDITOR if it resolves to an executable', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: 'editor', TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('editor')
+        .mockResolvedValue('/path/to/resolved-editor');
+
+      expect(await determineEditor()).toStrictEqual({
+        path: '/path/to/resolved-editor',
+        args: [],
+      });
+    });
+
+    it('falls back to VSCode if it exists and if EDITOR does not point to an executable', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: 'editor', TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('editor')
+        .mockResolvedValue(null)
+        .calledWith('code')
+        .mockResolvedValue('/path/to/code');
+
+      expect(await determineEditor()).toStrictEqual({
+        path: '/path/to/code',
+        args: ['--wait'],
+      });
+    });
+
+    it('returns null if resolving EDITOR returns null and resolving VSCode returns null', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: 'editor', TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('editor')
+        .mockResolvedValue(null)
+        .calledWith('code')
+        .mockResolvedValue(null);
+
+      expect(await determineEditor()).toBeNull();
+    });
+
+    it('returns null if resolving EDITOR returns null and resolving VSCode throws', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: 'editor', TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('editor')
+        .mockResolvedValue(null)
+        .calledWith('code')
+        .mockRejectedValue(new Error('some error'));
+
+      expect(await determineEditor()).toBeNull();
+    });
+
+    it('returns null if resolving EDITOR throws and resolving VSCode returns null', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: 'editor', TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('editor')
+        .mockRejectedValue(new Error('some error'))
+        .calledWith('code')
+        .mockResolvedValue(null);
+
+      expect(await determineEditor()).toBeNull();
+    });
+
+    it('returns null if resolving EDITOR throws and resolving VSCode throws', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: 'editor', TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('editor')
+        .mockRejectedValue(new Error('some error'))
+        .calledWith('code')
+        .mockRejectedValue(new Error('some error'));
+
+      expect(await determineEditor()).toBeNull();
+    });
+
+    it('returns null if EDITOR is unset and resolving VSCode returns null', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: undefined, TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('code')
+        .mockResolvedValue(null);
+
+      expect(await determineEditor()).toBeNull();
+    });
+
+    it('returns null if EDITOR is unset and resolving VSCode throws', async () => {
+      jest
+        .spyOn(envModule, 'getEnvironmentVariables')
+        .mockReturnValue({ EDITOR: undefined, TODAY: undefined });
+      when(jest.spyOn(miscUtils, 'resolveExecutable'))
+        .calledWith('code')
+        .mockRejectedValue(new Error('some error'));
+
+      expect(await determineEditor()).toBeNull();
+    });
+  });
+});

src/editor.ts

@@ -0,0 +1,56 @@
+import { getEnvironmentVariables } from './env';
+import { debug, resolveExecutable } from './misc-utils';
+
+/**
+ * Information about the editor present on the user's computer.
+ *
+ * @property path - The path to the executable representing the editor.
+ * @property args - Command-line arguments to pass to the executable when
+ * calling it.
+ */
+export interface Editor {
+  path: string;
+  args: string[];
+}
+
+/**
+ * Looks for an executable that represents a code editor on your computer. Tries
+ * the `EDITOR` environment variable first, falling back to the executable that
+ * represents VSCode (`code`).
+ *
+ * @returns A promise that contains information about the found editor (path and
+ * arguments), or null otherwise.
+ */
+export async function determineEditor(): Promise<Editor | null> {
+  let executablePath: string | null = null;
+  const executableArgs: string[] = [];
+  const { EDITOR } = getEnvironmentVariables();
+
+  if (EDITOR !== undefined) {
+    try {
+      executablePath = await resolveExecutable(EDITOR);
+    } catch (error) {
+      debug(
+        `Could not resolve executable ${EDITOR} (${error}), falling back to VSCode`,
+      );
+    }
+  }
+
+  if (executablePath === null) {
+    try {
+      executablePath = await resolveExecutable('code');
+      // Waits until the file is closed before returning
+      executableArgs.push('--wait');
+    } catch (error) {
+      debug(
+        `Could not resolve path to VSCode: ${error}, continuing regardless`,
+      );
+    }
+  }
+
+  if (executablePath !== null) {
+    return { path: executablePath, args: executableArgs };
+  }
+
+  return null;
+}

src/env.test.ts

@@ -0,0 +1,28 @@
+import { getEnvironmentVariables } from './env';
+
+describe('env', () => {
+  describe('getEnvironmentVariables', () => {
+    let existingProcessEnv: NodeJS.ProcessEnv;
+
+    beforeEach(() => {
+      existingProcessEnv = { ...process.env };
+    });
+
+    afterEach(() => {
+      Object.keys(existingProcessEnv).forEach((key) => {
+        process.env[key] = existingProcessEnv[key];
+      });
+    });
+
+    it('returns only the environment variables from process.env that we use in this tool', () => {
+      process.env.EDITOR = 'editor';
+      process.env.TODAY = 'today';
+      process.env.EXTRA = 'extra';
+
+      expect(getEnvironmentVariables()).toStrictEqual({
+        EDITOR: 'editor',
+        TODAY: 'today',
+      });
+    });
+  });
+});