feat: add basic cli

Author: skovy

README.md

@@ -2,21 +2,74 @@
 
 css-codemod is a toolkit for running codemods (a.k.a. transforms) over many CSS files.
 
-## Install
+## Usage
 
-TODO
+There are two ways to use css-codemod.
 
-## Usage
+First, using [npx](https://www.npmjs.com/package/npx) to execute the transform without need to explicitly install `css-codemod`.
+
+```bash
+npx css-codemod ./src/**/*.css -t ./transform.ts
+```
+
+Second, install `css-codemod` as a dependency and execute with your package manager of choice.
+
+```bash
+# Install and execute css-codemod with npm
+npm i -D css-codemod
+./node_modules/.bin/css-codemod ./src/**/*.css -t ./transform.ts
+
+# Or, install and execute css-codemod with yarn
+yarn add -D css-codemod
+yarn css-codemod ./src/**/*.css -t ./transform.ts
+```
+
+## Transform
+
+The transform file defines the transformations to define. The transform can be written in either JavaScript or TypeScript.
+
+```ts
+// transform.ts
+
+// Import the `Transform` type to provide type-safety when
+// using and creating a transform function.
+import { Transform } from 'css-codemod';
+
+// Define a named `transform` export.
+// Note: it's important the function is named `transform` because that's
+// what the tool expects.
+export const transform: Transform = (file, api) => {
+  // Implement the transform.
+};
+```
+
+## CLI
+
+```bash
+Usage:
+  $ css-codemod [files]
+
+Commands:
+  [files]  File path to transform. Glob patterns are supported.
 
-TODO
+For more info, run any command with the `--help` flag:
+  $ css-codemod --help
 
-### CLI
+Options:
+  -t, --transform <transform>  Path to the transform file (default: ./transform.ts)
+  -h, --help                   Display this message
+  -v, --version                Display version number
 
-TODO
+Examples:
+css-codemod ./a.css
+css-codemod ./src/a.css
+css-codemod ./src/**/*.css
+css-codemod ./**/*.css
+```
 
-### API
+## API
 
-TODO
+TODO(Document transform function API)
 
 ### PostCSS
 

package.json

@@ -23,7 +23,8 @@
     "prepare": "yarn build",
     "size": "size-limit",
     "analyze": "size-limit --why",
-    "clean": "rimraf dist"
+    "clean": "rimraf dist",
+    "css-codemod": "yarn build && ./dist/cli.js"
   },
   "husky": {
     "hooks": {
@@ -48,6 +49,7 @@
   ],
   "devDependencies": {
     "@size-limit/preset-small-lib": "^7.0.5",
+    "@types/node": "^17.0.13",
     "dripip": "^0.10.0",
     "husky": "^7.0.4",
     "rimraf": "^3.0.2",
@@ -58,6 +60,10 @@
     "typescript": "^4.5.5"
   },
   "dependencies": {
+    "bundle-require": "^3.0.2",
+    "cac": "^6.7.12",
+    "esbuild": "^0.14.14",
+    "glob": "^7.2.0",
     "postcss": "^8.4.5"
   }
 }

src/cli.ts

@@ -1,3 +1,38 @@
 #!/usr/bin/env node
 
-console.log('hello world.');
+import { cac } from 'cac';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { processTransform } from './process-transform';
+
+const PACKAGE_PATH = join(__dirname, '../package.json');
+const PACKAGE_JSON = JSON.parse(readFileSync(PACKAGE_PATH, 'utf8'));
+const NAME = PACKAGE_JSON.name;
+const VERSION = PACKAGE_JSON.version;
+
+const run = async () => {
+  const cli = cac(`${NAME}`);
+
+  cli
+    .command('[files]', 'File path to transform. Glob patterns are supported.')
+    .example(`${NAME} ./a.css`)
+    .example(`${NAME} ./src/a.css`)
+    .example(`${NAME} ./src/**/*.css`)
+    .example(`${NAME} ./**/*.css`)
+    .option('-t, --transform <transform>', 'Path to the transform file', {
+      default: './transform.ts',
+    })
+    .action(async (files: string[], flags) => {
+      const { transform } = flags;
+
+      await processTransform({ files, transform });
+    });
+
+  cli.help();
+  cli.version(VERSION);
+  cli.parse(process.argv, { run: false });
+
+  await cli.runMatchedCommand();
+};
+
+run();

src/load-transform.ts

@@ -0,0 +1,38 @@
+import { bundleRequire } from 'bundle-require';
+import { Transform } from './transform';
+
+const MINIMUM_EXAMPLE_TRANSFORM = `
+  import { Transform } from "css-codemod";
+
+  export const transform: Transform = (file, api) => {};
+`;
+
+/**
+ * Validate the general structure of the transform to catch simple errors.
+ */
+const validateTransform = (transform: unknown): Transform => {
+  if (typeof transform === 'function') {
+    return transform as Transform;
+  } else {
+    console.error(
+      `Transform file must export a valid transform. For example:\n${MINIMUM_EXAMPLE_TRANSFORM}`
+    );
+    process.exit(1);
+  }
+};
+
+/**
+ * Load and validate the transform file given the filepath.
+ */
+export const loadTransform = async (filepath: string): Promise<Transform> => {
+  try {
+    const { mod } = await bundleRequire({ filepath });
+    const transform = validateTransform(mod.transform || mod.default);
+    return transform;
+  } catch (err) {
+    console.error(
+      `An error occurred loading the transform file. Verify "${filepath}" exists.`
+    );
+    process.exit(1);
+  }
+};

src/process-transform.ts

@@ -0,0 +1,20 @@
+import { loadTransform } from './load-transform';
+
+interface ProcessTransformOptions {
+  /**
+   * The list of file paths to process and run through the transform.
+   */
+  files: string[];
+
+  /**
+   * The transform path to run each file through.
+   */
+  transform: string;
+}
+
+export const processTransform = async (options: ProcessTransformOptions) => {
+  console.log(options);
+  const transform = await loadTransform(options.transform);
+
+  transform();
+};

src/transform.ts

@@ -0,0 +1,8 @@
+interface TransformFileInfo {}
+
+interface TransformAPI {}
+
+export type Transform = (
+  fileInfo: TransformFileInfo,
+  api: TransformAPI
+) => null | string;

test/transforms/color-to-red.ts

@@ -0,0 +1,3 @@
+export const t = () => {
+  console.log('HELLO WORLD TRANSFORM.');
+};

tsconfig.json

@@ -21,8 +21,6 @@
     "noUnusedParameters": true,
     // use Node's module resolution algorithm, instead of the legacy TS one
     "moduleResolution": "node",
-    // transpile JSX to React.createElement
-    "jsx": "react",
     // interop between ESM and CJS modules. Recommended by TS
     "esModuleInterop": true,
     // significant perf increase by skipping checking .d.ts files, particularly those in node_modules. Recommended by TS

yarn.lock

@@ -1529,7 +1529,7 @@
   resolved "https://registry.yarnpkg.com/@types/ms/-/ms-0.7.31.tgz#31b7ca6407128a3d2bbc27fe2d21b345397f6197"
   integrity sha512-iiUgKzV9AuaEkZqkOLDIvlQiL6ltuZd9tGcW3gwpnX8JbuiuhFlEGmmFXEXkN50Cvq7Os88IY2v0dkDqXYWVgA==
 
-"@types/node@*":
+"@types/node@*", "@types/node@^17.0.13":
   version "17.0.13"
   resolved "https://registry.yarnpkg.com/@types/node/-/node-17.0.13.tgz#5ed7ed7c662948335fcad6c412bb42d99ea754e3"
   integrity sha512-Y86MAxASe25hNzlDbsviXl8jQHb0RDvKt4c40ZJQ1Don0AAL0STLZSs4N+6gLEO55pedy7r2cLwS+ZDxPm/2Bw==
@@ -2135,6 +2135,13 @@ bundle-require@^2.1.8:
   resolved "https://registry.yarnpkg.com/bundle-require/-/bundle-require-2.3.0.tgz#2d4d4968dd29d2de4b9ac1db98be495c73f5b2b8"
   integrity sha512-kH8vyERJv0Td4Odu2KQyooYyeXDx2FbhGwSfkEGdyHmkTCahvwVI8w/pE2stbsp6G/W5/3kIC7ErdBg/30OAkw==
 
+bundle-require@^3.0.2:
+  version "3.0.2"
+  resolved "https://registry.yarnpkg.com/bundle-require/-/bundle-require-3.0.2.tgz#900fbd84d84db6799e674fbebc74c4ba498651b5"
+  integrity sha512-WLS50LRdi8oAMnQfoxqjI3Fszi0xaI6dJumvtX909u0WREkYCuFGeE2UwMn5H8bSUXWtUB0XeBqNkgpVjMcYyQ==
+  dependencies:
+    load-tsconfig "^0.2.0"
+
 bytes-iec@^3.1.1:
   version "3.1.1"
   resolved "https://registry.yarnpkg.com/bytes-iec/-/bytes-iec-3.1.1.tgz#94cd36bf95c2c22a82002c247df8772d1d591083"
@@ -2845,7 +2852,7 @@ esbuild-windows-arm64@0.14.14:
   resolved "https://registry.yarnpkg.com/esbuild-windows-arm64/-/esbuild-windows-arm64-0.14.14.tgz#ca747ce4066d5b8a79dbe48fe6ecd92d202e5366"
   integrity sha512-dCm1wTOm6HIisLanmybvRKvaXZZo4yEVrHh1dY0v582GThXJOzuXGja1HIQgV09RpSHYRL3m4KoUBL00l6SWEg==
 
-esbuild@^0.14.2, esbuild@^0.14.8:
+esbuild@^0.14.14, esbuild@^0.14.2, esbuild@^0.14.8:
   version "0.14.14"
   resolved "https://registry.yarnpkg.com/esbuild/-/esbuild-0.14.14.tgz#3b99f20d628013c3e2ae90e67687e03f1d6eb071"
   integrity sha512-aiK4ddv+uui0k52OqSHu4xxu+SzOim7Rlz4i25pMEiC8rlnGU0HJ9r+ZMfdWL5bzifg+nhnn7x4NSWTeehYblg==
@@ -3561,7 +3568,7 @@ glob@7.1.6:
     once "^1.3.0"
     path-is-absolute "^1.0.0"
 
-glob@^7.0.0, glob@^7.1.1, glob@^7.1.2, glob@^7.1.3, glob@^7.1.4, glob@^7.1.6:
+glob@^7.0.0, glob@^7.1.1, glob@^7.1.2, glob@^7.1.3, glob@^7.1.4, glob@^7.1.6, glob@^7.2.0:
   version "7.2.0"
   resolved "https://registry.yarnpkg.com/glob/-/glob-7.2.0.tgz#d15535af7732e02e948f4c41628bd910293f6023"
   integrity sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==
@@ -4790,6 +4797,11 @@ lines-and-columns@^1.1.6:
   resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.2.4.tgz#eca284f75d2965079309dc0ad9255abb2ebc1632"
   integrity sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==
 
+load-tsconfig@^0.2.0:
+  version "0.2.2"
+  resolved "https://registry.yarnpkg.com/load-tsconfig/-/load-tsconfig-0.2.2.tgz#1aaf97e37e34a847042598a7596f4a3163320e06"
+  integrity sha512-9B4XOMjNhphRmXg3YHFnpgEH5fmYKofXJ7M6sLkRcfJ5DcuPiStlQ1Or+1Rv/aML716kQ9Q+C9zJGUcfMYiq4Q==
+
 locate-path@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-2.0.0.tgz#2b568b265eec944c6d9c0de9c3dbbbca0354cd8e"