chore: clean branch

packages-node/migrate-cli/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog `migrate-cli`
+All notable changes to this project will be documented in this file. 
+
+## 0.1.0 - 2024-10-29
+
+### Initial commit
+
+- feat: added `cli` to run migrations
+- feat: export `MigrateCli`: class using `Commander` to provide a intuitive and adaptable CLI
+- feat: export `UpgradeCommandBase`: extendable command implementing upgrade behaviour
+- feat: export `executeJsCodeShiftTransforms`: function that runs `jscodeshift` on a codebase
+- test: added unit tests for classes
+- test: WIP e2e testing of CLI
+- test: WIP unit tests for `executeJsCodeShiftTransforms`
+- chore: added README

packages-node/migrate-cli/README.md

@@ -0,0 +1,123 @@
+# migrate-cli
+
+## What?
+
+The `migrate-cli` provides a more or less plug and play solution for running codemods / code transforms using (by default) JSCodeshift.
+
+## For whom?
+
+The CLI is aimed at platform developers that want to make migrations easy for their users. Using this CLI, they can focus on writing high quality code transforms, without worrying about the overhead that comes with managing a CLI.
+
+## How?
+
+```bash
+npx migrate-cli
+npx migrate-cli upgrade --help
+npx migrate-cli upgrade -t lib-foo-1-to-2 -u /path/to/upgrades/dir
+```
+
+### Migration tasks
+
+To use this CLI, you need one or more 'migration tasks'. These tasks are intended to perform a (part of a) migration on a certain codebase. A task can perform actions on single files (like updating a `package.json`), but are best used to perform actions on many files (rewriting of imports in all relevant `.js` files, change of API, etc.).
+
+The CLI expects migration tasks to be in the following structure:
+
+```bash
+├── lib-foo-2-to-3
+  ├── index.js
+  └── jscodeshift
+    ├── 01-some-api-transform.js
+    ├── 01-some-api-transform*-\_cjs-export.cjs
+    ├── 02-some-code-removal-transform.js
+    ├── 02-some-code-removal-transform*-_cjs-export.cjs
+    ├── 03-import-transform.js
+    ├── 03-import-transform_-\_cjs-export.cjs
+```
+
+### `index.js`
+
+Here `index.js` is the entry point to the migration task, and it must have a function with the following signature:
+
+```javascript
+export async function upgrade(jscsOpts, workspaceMeta) {
+  ...
+}
+```
+
+`jscsOpts` by default contains minimal information required for running the CLI. More options can be added by enriching the `jscsOpts` object in the CLI configuration.
+
+`workspaceMeta` contains information that is relevant when running the CLI in a monorepo.
+
+#### `executeJsCodeShiftTransforms`
+
+The function `executeJsCodeShiftTransforms` is exported by this project. Its signature is as follows:
+
+```javascript
+export async function executeJsCodeShiftTransforms(
+  inputDir,
+  transformsFolder,
+  jscsOptions = {},
+)
+```
+
+This function can be called from `index.js` to perform the transformations in `transformsFolder` (`jscodeshift` in the example above) against a codebase found in `inputDir`. By default, this function will also be passed in the `jscsOpts` as `transformFunction`, so that it does not need to be imported.
+
+### Basic usage
+
+With this structure in mind, a minimal implementation of the CLI can be used by running the following command in the root of a codebase:
+
+```bash
+npx migrate-cli upgrade -t lib-foo-2-to-3 -u /path/or/url/to/parent-dir/
+```
+
+When this is run, the following things will happen:
+
+- The CLI will look in the provided directory for a directory called `lib-foo-2-to-3`;
+- If found, it will call the `upgrade` function in `index.js`;
+
+#### Configuration
+
+By default, the CLI will look for a `migrate-cli.config.(m)js` in the folder where it is run. You can also provide a config file using the `-c` option of the `upgrade` command.
+
+The most common configurable properties are listed below:
+
+| Property             | Description                                                                      |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `inputDir`           | Root directory of the project to be migrated                                     |
+| `task`               | Upgrade task that should be performed                                            |
+| `jscsOpts`           | Options object passed to `index.js` of the upgrade                               |
+| `upgradesDir`        | URL or string providing the directory where one or more upgrades can be found    |
+| `upgradesConfigHref` | Upgrade specific configuration (defaults to `${upgradesDir}/upgrades.config.js`) |
+| `upgradeTaskUrl`     | Location of a specific upgrade task                                              |
+
+The upgrade command always needs to resolve to a specific task. Therefore, it will always require either a `task` and an `upgradesDir`, or an `upgradesTaskUrl`.
+
+### Advanced usage
+
+A user can also implement the CLI in their own project, allowing for more advanced functionality. A user can enhance the CLI in the following ways:
+
+1. By initializing the `MigrateCli` passing an `initOptions` object (allowing for additional commands, changing name and introduction text, etc.);
+2. By extending the `UpgradeCommandBase` class to suit their specific needs.
+
+#### Example of initializing with initial options
+
+An example implementation of (1):
+
+```javascript
+import { MigrateCli } from './MigrateCli.js';
+import path from 'path';
+
+const initOptions = {
+  cliOptions: {
+    upgradesUrl: new URL('./upgrades', import.meta.url), // will look for potential upgrades in this directory
+  },
+  commandsUrls: [new URL('./commands', import.meta.url)], // allows for more (or more specific) commands to be loaded from this directory
+  includeBaseCommands: false, // if true, UpgradeBaseCommand will be included as well as user specified commands
+  cliIntroductionText: `Welcome to lib-foo-migrate CLI 👋\n`,
+  pathToPkgJson: path.resolve(dirname(fileURLToPath(import.meta.url)), '../package.json'), // specify so version can be retrieved
+};
+
+const cli = new MigrateCli(initOptions);
+
+cli.start();
+```

packages-node/migrate-cli/index.js

@@ -0,0 +1,4 @@
+export { MigrateCli } from './src/MigrateCli.js';
+export { UpgradeCommandBase } from './src/commands/UpgradeCommandBase.js';
+
+export { executeJsCodeShiftTransforms } from './src/migrate-helpers/executeJsCodeShiftTransforms.js';

packages-node/migrate-cli/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "migrate-cli",
+  "version": "0.1.0",
+  "description": "CLI to execute migration with custom transforms",
+  "author": "ing-bank",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ing-bank/lion.git",
+    "directory": "packages-node/migrate-cli"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "migrate-cli": "src/cli.js"
+  },
+  "scripts": {
+    "lint": "eslint . && prettier \"**/*.js\" --check --ignore-path .lintignore",
+    "test": "mocha test/**/*.test.js --timeout 8000",
+    "types": "wireit"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "globby": "^14.0.2",
+    "jscodeshift": "^17.1.1",
+    "prompts": "^2.4.2",
+    "providence-analytics": "^0.17.0",
+    "semver": "^7.6.3"
+  },
+  "devDependencies": {
+    "@types/jscodeshift": "^0.11.11",
+    "@types/semver": "^7.5.8",
+    "chai-as-promised": "^8.0.0",
+    "mock-require": "^3.0.3"
+  },
+  "keywords": [
+    "cli",
+    "codemod",
+    "jscodeshift",
+    "migrate"
+  ],
+  "wireit": {
+    "types": {
+      "command": "tsc --build --pretty",
+      "files": [
+        "src",
+        "test-node",
+        "types",
+        "tsconfig.json"
+      ],
+      "output": [
+        "dist-types/**"
+      ]
+    }
+  }
+}

packages-node/migrate-cli/src/MigrateCli.js

@@ -0,0 +1,180 @@
+/* eslint-disable new-cap, no-await-in-loop, no-console */
+import { Command } from 'commander';
+import path, { dirname } from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+import { mergeDeep } from './cli-helpers/mergeDeep.js';
+import { AsyncEventEmitter } from './cli-helpers/AsyncEventEmitter.js';
+
+/**
+ * @typedef {{ plugins: {setupCommand:function;stop:function}[]; argv:string[];commandsUrls:URL[]}} Config
+ * @typedef {import('../types/index.js').Options}Options
+ * @typedef {import('../types/index.js').InitOptions}InitOptions
+ */
+
+export class MigrateCli {
+  /** @type {Options} */
+  options = {
+    // Codemod options
+    configFile: '',
+    inputDir: 'FALLBACK',
+    cwd: process.cwd(),
+    jscsOpts: {},
+    upgradeTaskUrl: '',
+    upgradesDir: '',
+    _upgradesDirUrl: undefined,
+    upgradeTaskNames: [],
+  };
+
+  events = new AsyncEventEmitter();
+
+  /** @type {{setupCommand: function; upgrade?:function; runDoctorTask?:function}|undefined} */
+  activePlugin = undefined;
+
+  /**
+   * @param {InitOptions} initOptions
+   */
+  constructor(initOptions = {}) {
+    /** @type {Config} */
+    this.config = {
+      argv: initOptions.argv || process.argv,
+      commandsUrls: initOptions.commandsUrls || [],
+      plugins: initOptions.plugins || [],
+    };
+
+    if (!this.config.commandsUrls.length || initOptions.includeBaseCommands) {
+      this.config.commandsUrls.push(new URL('./commands', import.meta.url));
+    }
+    this.program = new Command();
+    // TODO: for later find a way to accept a config file without overriding the build in help
+    // this.program.allowUnknownOption().option('-c, --config-file <path>', 'path to config file');
+    // this.program.parse(this.config.argv);
+
+    this.program.allowUnknownOption(false);
+    this.program.addHelpText(
+      'before',
+      initOptions.cliIntroductionText || `Welcome to the migrate CLI 👋\n`,
+    );
+    this.pathToPkgJson =
+      initOptions.pathToPkgJson ||
+      path.resolve(dirname(fileURLToPath(import.meta.url)), '../package.json');
+
+    if (initOptions.options) {
+      this.setOptions(initOptions.options);
+    }
+
+    const { name, version } = this.getNameAndVersion();
+    this.program.version(initOptions.cliVersion || version, '-v, --version');
+    this.program.name = () => name;
+    if (this.program.opts().configFile) {
+      this.options.configFile = this.program.opts().configFile;
+    }
+  }
+
+  getNameAndVersion() {
+    try {
+      const pkgJsonContents = JSON.parse(fs.readFileSync(this.pathToPkgJson, 'utf8'));
+      return {
+        version: pkgJsonContents.version || 'N/A',
+        name: pkgJsonContents.name || 'N/A',
+      };
+    } catch (err) {
+      console.log(`No package.json file was detected for path ${this.pathToPkgJson}.`);
+      return {
+        version: 'Version unknown',
+        name: 'Name unknown',
+      };
+    }
+  }
+
+  /**
+   * @param {Options|{}} newOptions
+   */
+  setOptions(newOptions) {
+    // @ts-ignore
+    this.options = mergeDeep(this.options, newOptions);
+
+    if (this.options.inputDir === 'FALLBACK') {
+      this.options.inputDir = path.join(this.options.cwd);
+    }
+  }
+
+  /**
+   * @param {string} [configFile]
+   */
+  async applyConfigFile(configFile) {
+    const _configFile = configFile || this.options.configFile;
+    if (_configFile) {
+      const configFilePath = path.resolve(_configFile);
+      const fileOptions = (await import(configFilePath)).default;
+      this.setOptions(fileOptions);
+    } else {
+      // make sure all default settings are properly initialized
+      this.setOptions({});
+    }
+  }
+
+  async prepare() {
+    let pluginsMeta = [];
+    for (const commandsUrl of this.config.commandsUrls) {
+      const commandFileDir = fs.readdirSync(commandsUrl);
+      for (const commandFile of commandFileDir) {
+        const commandImport = await import(`${commandsUrl.pathname}/${commandFile}`);
+        const command = commandImport[Object.keys(commandImport)[0]];
+        pluginsMeta.push({ plugin: command, options: {} });
+      }
+    }
+    if (Array.isArray(this.options.setupCliPlugins)) {
+      for (const setupFn of this.options.setupCliPlugins) {
+        // @ts-ignore
+        pluginsMeta = setupFn(pluginsMeta);
+      }
+    }
+
+    for (const pluginObj of pluginsMeta) {
+      const pluginInst = pluginObj.options
+        ? // @ts-ignore
+          new pluginObj.plugin(pluginObj.options)
+        : // @ts-ignore
+          new pluginObj.plugin();
+      this.config.plugins.push(pluginInst);
+    }
+  }
+
+  async start() {
+    await this.applyConfigFile();
+    await this.prepare();
+
+    if (!this.config.plugins) {
+      return;
+    }
+
+    for (const plugin of this.config.plugins) {
+      if (plugin.setupCommand) {
+        await plugin.setupCommand(this.program, this);
+      }
+    }
+    try {
+      await this.program.parseAsync(this.config.argv);
+    } catch (error) {
+      // @ts-ignore
+      if (error.action) {
+        // @ts-ignore
+        await error.action();
+      }
+      throw error;
+    }
+  }
+
+  async stop({ hard = true } = {}) {
+    if (!this.config.plugins) {
+      return;
+    }
+    for (const plugin of this.config.plugins) {
+      if (plugin.stop) {
+        await plugin.stop({ hard });
+      }
+    }
+  }
+}