Placeholder for transforms with information in help (#12)

.changeset/pink-teachers-dress.md

@@ -0,0 +1,5 @@
+---
+"aws-sdk-js-codemod": patch
+---
+
+Adds a placeholder for transforms with information under help option

package.json

@@ -34,7 +34,8 @@
   },
   "dependencies": {
     "jscodeshift": "0.13.1",
-    "jscodeshift-find-imports": "2.0.4"
+    "jscodeshift-find-imports": "2.0.4",
+    "table": "6.8.0"
   },
   "devDependencies": {
     "@changesets/cli": "2.21.0",

src/cli.ts

@@ -5,10 +5,15 @@ import { spawn } from "child_process";
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore: package.json will be imported from dist folders
 import { version } from "../package.json"; // eslint-disable-line
+import { getHelpParagraph, getTransforms } from "./utils";
+
+export const run = async (args: string[]): Promise<void> => {
+  const transforms = getTransforms();
 
-export const run = async (args): Promise<void> => {
   if (args[0] === "--version") {
     process.stdout.write(`aws-sdk-js-codemod: ${version}\n\n`);
+  } else if (args[0] === "--help" || args[0] === "-h") {
+    process.stdout.write(getHelpParagraph(transforms));
   }
   spawn("npm", ["exec", "jscodeshift", "--", ...args], {
     stdio: "inherit",

src/transforms/index.ts

@@ -0,0 +1 @@
+export * from "./types";

src/transforms/types.ts

@@ -0,0 +1,26 @@
+export type PositionalOptionsType = "boolean" | "number" | "string";
+
+export interface AwsSdkJsCodemodTransformOption {
+  /** array of values, limit valid option arguments to a predefined set */
+  choices?: ReadonlyArray<boolean> | ReadonlyArray<number> | ReadonlyArray<string>;
+
+  /** value, set a default value for the option */
+  default?: boolean | number | string;
+
+  /** string, the option description for help content */
+  description: string;
+
+  /** string, the type of the option */
+  type: PositionalOptionsType;
+}
+
+export interface AwsSdkJsCodemodTransform {
+  /** string, the name of the transform */
+  name: string;
+
+  /** string, the description of the transform for help content */
+  description: string;
+
+  /** array of TransformOption, the which can be passed to the transform */
+  options: AwsSdkJsCodemodTransformOption[];
+}

src/transforms/v2-to-v3/transform.ts

@@ -0,0 +1,8 @@
+export const name = "v2-to-v3";
+
+export const description =
+  "Converts AWS SDK for JavaScript APIs in a Javascript/TypeScript codebase" +
+  " from version 2 (v2) to version 3 (v3).";
+
+// Additional options will come here, like running on specific clients.
+export const options = [];

src/transforms/v2-to-v3/transformer.ts

@@ -0,0 +1,10 @@
+import { API, FileInfo } from "jscodeshift";
+
+export default function transformer(file: FileInfo, api: API) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  // transform `root` here
+
+  return root.toSource();
+}

src/utils/getHelpParagraph.ts

@@ -0,0 +1,23 @@
+import { getBorderCharacters, table } from "table";
+
+import { AwsSdkJsCodemodTransform } from "../transforms";
+
+export const getHelpParagraph = (transforms: AwsSdkJsCodemodTransform[]) =>
+  `----------------------------------------------------------------------------------------------------
+aws-sdk-js-codemod is a lightweight wrapper over jscodeshift.
+It processes --help, --version and --transform options before passing them downstream.
+
+You can provide names of the custom transforms instead of a local path or url:
+
+${table(
+  transforms.map(({ name, description }) => [name, description]),
+  {
+    border: getBorderCharacters("void"),
+    columns: [
+      { width: 12, alignment: "right" },
+      { width: 88, wrapWord: true },
+    ],
+  }
+)}Example: aws-sdk-js-codemod -t v2-to-v3 example.js
+
+----------------------------------------------------------------------------------------------------\n\n`;

src/utils/getTransforms.ts

@@ -0,0 +1,13 @@
+import { readdirSync } from "fs";
+import { join } from "path";
+
+import { AwsSdkJsCodemodTransform } from "../transforms";
+
+export const getTransforms = () =>
+  readdirSync(join(__dirname, "..", "transforms"), { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => dirent.name)
+    .map((dirName) => {
+      const { name, description, options } = require(`../transforms/${dirName}/transform`); // eslint-disable-line
+      return { name, description, options } as AwsSdkJsCodemodTransform;
+    });

src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./getHelpParagraph";
+export * from "./getTransforms";

yarn.lock

@@ -1628,6 +1628,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ajv@npm:^8.0.1":
+  version: 8.10.0
+  resolution: "ajv@npm:8.10.0"
+  dependencies:
+    fast-deep-equal: ^3.1.1
+    json-schema-traverse: ^1.0.0
+    require-from-string: ^2.0.2
+    uri-js: ^4.2.2
+  checksum: 3594728ef1e31219ef97bfacb203d0d72db8ad5c35d6d0578e38ee453e4537c2bf927dad144bb84b0c893f661d71b58337d4643e8ee2f2a6e1d63b041c92fe82
+  languageName: node
+  linkType: hard
+
 "ansi-colors@npm:^4.1.1":
   version: 4.1.1
   resolution: "ansi-colors@npm:4.1.1"
@@ -1833,6 +1845,7 @@ __metadata:
     lint-staged: 12.3.4
     prettier: 2.5.1
     simple-git-hooks: 2.7.0
+    table: 6.8.0
     ts-jest: 27.1.3
     typescript: 4.5.5
   bin:
@@ -4685,6 +4698,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"json-schema-traverse@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "json-schema-traverse@npm:1.0.0"
+  checksum: 02f2f466cdb0362558b2f1fd5e15cce82ef55d60cd7f8fa828cf35ba74330f8d767fcae5c5c2adb7851fa811766c694b9405810879bc4e1ddd78a7c0e03658ad
+  languageName: node
+  linkType: hard
+
 "json-stable-stringify-without-jsonify@npm:^1.0.1":
   version: 1.0.1
   resolution: "json-stable-stringify-without-jsonify@npm:1.0.1"
@@ -4900,6 +4920,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"lodash.truncate@npm:^4.4.2":
+  version: 4.4.2
+  resolution: "lodash.truncate@npm:4.4.2"
+  checksum: b463d8a382cfb5f0e71c504dcb6f807a7bd379ff1ea216669aa42c52fc28c54e404bfbd96791aa09e6df0de2c1d7b8f1b7f4b1a61f324d38fe98bc535aeee4f5
+  languageName: node
+  linkType: hard
+
 "lodash@npm:^4.7.0":
   version: 4.17.21
   resolution: "lodash@npm:4.17.21"
@@ -5972,6 +5999,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"require-from-string@npm:^2.0.2":
+  version: 2.0.2
+  resolution: "require-from-string@npm:2.0.2"
+  checksum: a03ef6895445f33a4015300c426699bc66b2b044ba7b670aa238610381b56d3f07c686251740d575e22f4c87531ba662d06937508f0f3c0f1ddc04db3130560b
+  languageName: node
+  linkType: hard
+
 "require-main-filename@npm:^2.0.0":
   version: 2.0.0
   resolution: "require-main-filename@npm:2.0.0"
@@ -6698,6 +6732,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"table@npm:6.8.0":
+  version: 6.8.0
+  resolution: "table@npm:6.8.0"
+  dependencies:
+    ajv: ^8.0.1
+    lodash.truncate: ^4.4.2
+    slice-ansi: ^4.0.0
+    string-width: ^4.2.3
+    strip-ansi: ^6.0.1
+  checksum: 5b07fe462ee03d2e1fac02cbb578efd2e0b55ac07e3d3db2e950aa9570ade5a4a2b8d3c15e9f25c89e4e50b646bc4269934601ee1eef4ca7968ad31960977690
+  languageName: node
+  linkType: hard
+
 "tar@npm:^6.0.2, tar@npm:^6.1.2":
   version: 6.1.11
   resolution: "tar@npm:6.1.11"