@kamaalio/codemod-kit 0.0.1

package/README.md

@@ -0,0 +1,116 @@
+# Codemod kit
+
+A toolkit to run codemods.
+
+## Installation
+
+```bash
+pnpm add @kamaalio/codemod-kit
+```
+
+## Usage
+
+```typescript
+import { runCodemods } from '@kamaalio/codemod-kit';
+import type { CodeMod } from '@kamaalio/codemod-kit';
+
+const myCodemod: CodeMod = {
+  name: 'my-codemod',
+  languages: ['typescript'],
+  commitMessage: 'feat(codemod): my first codemod',
+  transformer: async (content, filename) => {
+    // ... transform the content
+  },
+};
+
+runCodemods([myCodemod], './src');
+```
+
+## API
+
+### `runCodemods(codemods, transformationPath, options?)`
+
+Runs a list of codemods on a given path.
+
+- `codemods`: An array of `Codemod` objects.
+- `transformationPath`: The path to the directory to transform.
+- `options`: Optional configuration for the run.
+
+### `runCodemod(codemod, transformationPath, globItems, options?)`
+
+Runs a single codemod.
+
+- `codemod`: A `Codemod` object.
+- `transformationPath`: The path to the directory to transform.
+- `globItems`: An array of file paths to transform.
+- `options`: Optional configuration for the run.
+
+### `Codemod`
+
+A codemod is defined by the `Codemod` type:
+
+```typescript
+export type Codemod = {
+  name: string;
+  languages: Set<NapiLang> | Array<NapiLang>;
+  commitMessage: string;
+  transformer: (content: SgRoot<TypesMap> | string, filename?: Optional<string>) => Promise<Modifications>;
+};
+```
+
+- `name`: The name of the codemod.
+- `languages`: The languages the codemod applies to.
+- `commitMessage`: The commit message to use when applying the codemod.
+- `transformer`: The function that transforms the code.
+
+### `Modifications`
+
+The `transformer` function returns a `Modifications` object:
+
+```typescript
+export type Modifications = {
+  ast: SgRoot<TypesMap>;
+  report: ModificationsReport;
+  lang: NapiLang;
+  filename: Optional<string>;
+  history: Array<SgRoot<TypesMap>>;
+};
+```
+
+- `ast`: The modified AST.
+- `report`: A report of the changes.
+- `lang`: The language of the file.
+- `filename`: The name of the file.
+- `history`: A history of the modifications.
+
+## Hooks
+
+You can provide hooks to customize the codemod run:
+
+```typescript
+type RunCodemodHooks = {
+  targetFiltering?: (filepath: string) => boolean;
+  preCodemodRun?: (codemod: Codemod) => Promise<void>;
+  postTransform?: (transformedContent: string) => Promise<string>;
+};
+```
+
+- `targetFiltering`: A function to filter the files to transform.
+- `preCodemodRun`: A function to run before each codemod.
+- `postTransform`: A function to run after each transformation.
+
+## Options
+
+You can provide options to customize the codemod run:
+
+```typescript
+type RunCodemodOptions = {
+  hooks?: RunCodemodHooks;
+  log?: boolean;
+  dry?: boolean;
+};
+```
+
+- `hooks`: The hooks to use.
+- `log`: Whether to log the output.
+- `dry`: Whether to run in dry mode (no changes are written to disk).

package/dist/codemods/constants.d.ts

@@ -0,0 +1 @@
+export declare const LANG_TO_EXTENSIONS_MAPPING: Partial<Record<string, Set<string>>>;

package/dist/codemods/index.d.ts

@@ -0,0 +1,2 @@
+export { runCodemods, runCodemod } from './utils';
+export type { Codemod, Modifications } from './types';

package/dist/codemods/types.d.ts

@@ -0,0 +1,20 @@
+import type { SgRoot } from '@ast-grep/napi';
+import type { NapiLang } from '@ast-grep/napi/types/lang.js';
+import type { TypesMap } from '@ast-grep/napi/types/staticTypes.js';
+import type { Optional } from '../utils/type-utils';
+export type Codemod = {
+    name: string;
+    languages: Set<NapiLang> | Array<NapiLang>;
+    commitMessage: string;
+    transformer: (content: SgRoot<TypesMap> | string, filename?: Optional<string>) => Promise<Modifications>;
+};
+export type ModificationsReport = {
+    changesApplied: number;
+};
+export type Modifications = {
+    ast: SgRoot<TypesMap>;
+    report: ModificationsReport;
+    lang: NapiLang;
+    filename: Optional<string>;
+    history: Array<SgRoot<TypesMap>>;
+};

package/dist/codemods/utils.d.ts

@@ -0,0 +1,15 @@
+import { type Result } from 'neverthrow';
+import type { Codemod, Modifications } from './types';
+type RunCodemodHooks = {
+    targetFiltering?: (filepath: string) => boolean;
+    preCodemodRun?: (codemod: Codemod) => Promise<void>;
+    postTransform?: (transformedContent: string) => Promise<string>;
+};
+type RunCodemodOptions = {
+    hooks?: RunCodemodHooks;
+    log?: boolean;
+    dry?: boolean;
+};
+export declare function runCodemods(codemods: Array<Codemod>, transformationPath: string, options?: RunCodemodOptions): Promise<Record<string, Array<Result<Modifications, Error>>>>;
+export declare function runCodemod(codemod: Codemod, transformationPath: string, globItems: Array<string>, options?: RunCodemodOptions): Promise<Array<Result<Modifications, Error>>>;
+export {};

package/dist/index.cjs

@@ -0,0 +1,137 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    runCodemod: ()=>runCodemod,
+    runCodemods: ()=>runCodemods
+});
+const external_node_path_namespaceObject = require("node:path");
+var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
+const promises_namespaceObject = require("node:fs/promises");
+var promises_default = /*#__PURE__*/ __webpack_require__.n(promises_namespaceObject);
+const external_fast_glob_namespaceObject = require("fast-glob");
+var external_fast_glob_default = /*#__PURE__*/ __webpack_require__.n(external_fast_glob_namespaceObject);
+const external_neverthrow_namespaceObject = require("neverthrow");
+const napi_namespaceObject = require("@ast-grep/napi");
+const LANG_TO_EXTENSIONS_MAPPING = {
+    [napi_namespaceObject.Lang.TypeScript.toLowerCase()]: new Set([
+        '.ts',
+        '.tsx',
+        '.js',
+        '.jsx',
+        '.cjs',
+        '.mjs',
+        '.mts'
+    ])
+};
+function getCollectionCount(collection) {
+    if (Array.isArray(collection)) return collection.length;
+    return collection.size;
+}
+function collectionIsEmpty(collection) {
+    return 0 === getCollectionCount(collection);
+}
+async function runCodemods(codemods, transformationPath, options) {
+    const globItems = await external_fast_glob_default().glob([
+        '**/*'
+    ], {
+        cwd: transformationPath
+    });
+    const results = {};
+    for (const codemod of codemods)results[codemod.name] = await runCodemod(codemod, transformationPath, globItems, options);
+    return results;
+}
+async function runCodemod(codemod, transformationPath, globItems, options) {
+    const { hooks, log: enableLogging, dry: runInDryMode } = defaultedOptions(options);
+    const extensions = new Set(Array.from(codemod.languages).reduce((acc, language)=>{
+        const mappedExtensions = LANG_TO_EXTENSIONS_MAPPING[language.toLowerCase()];
+        if (null == mappedExtensions) return acc;
+        return acc.concat(Array.from(mappedExtensions));
+    }, []));
+    const targets = globItems.filter((filepath)=>{
+        if (!hooks.targetFiltering(filepath)) return false;
+        const projectName = filepath.split('/')[0];
+        if (null == projectName) throw new Error('Invariant found, project name should be present');
+        return collectionIsEmpty(extensions) || extensions.has(external_node_path_default().extname(filepath));
+    });
+    if (0 === targets.length) return [];
+    if (enableLogging) console.log(`\u{1F9C9} '${codemod.name}' targeting ${targets.length} ${1 === targets.length ? 'file' : 'files'} to transform, chill and grab some mat\xe9`);
+    return Promise.all(targets.map(async (filepath)=>{
+        const fullPath = external_node_path_default().join(transformationPath, filepath);
+        try {
+            const content = await promises_default().readFile(fullPath, {
+                encoding: 'utf-8'
+            });
+            const modifications = await codemod.transformer(content, fullPath);
+            if (modifications.report.changesApplied > 0) {
+                const transformedContent = await hooks.postTransform(modifications.ast.root().text());
+                if (!runInDryMode) await promises_default().writeFile(fullPath, transformedContent);
+                if (enableLogging) console.log(`\u{1F680} finished '${codemod.name}'`, {
+                    filename: filepath,
+                    report: modifications.report
+                });
+            }
+            return (0, external_neverthrow_namespaceObject.ok)(modifications);
+        } catch (error) {
+            if (enableLogging) console.error(`\u{274C} '${codemod.name}' failed to parse file`, filepath, error);
+            return (0, external_neverthrow_namespaceObject.err)(error);
+        }
+    }));
+}
+function defaultedOptions(options) {
+    return {
+        hooks: defaultedHooks(options?.hooks),
+        log: options?.log ?? true,
+        dry: options?.dry ?? false
+    };
+}
+function defaultedHooks(hooks) {
+    const targetFiltering = hooks?.targetFiltering ?? (()=>true);
+    const postTransform = hooks?.postTransform ?? (async (content)=>content);
+    const preCodemodRun = hooks?.preCodemodRun ?? (async ()=>{});
+    return {
+        targetFiltering,
+        postTransform,
+        preCodemodRun
+    };
+}
+exports.runCodemod = __webpack_exports__.runCodemod;
+exports.runCodemods = __webpack_exports__.runCodemods;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "runCodemod",
+    "runCodemods"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { runCodemods, runCodemod, type Codemod } from './codemods';

package/dist/index.js

@@ -0,0 +1,88 @@
+import node_path from "node:path";
+import promises from "node:fs/promises";
+import fast_glob from "fast-glob";
+import { err, ok } from "neverthrow";
+import { Lang } from "@ast-grep/napi";
+const LANG_TO_EXTENSIONS_MAPPING = {
+    [Lang.TypeScript.toLowerCase()]: new Set([
+        '.ts',
+        '.tsx',
+        '.js',
+        '.jsx',
+        '.cjs',
+        '.mjs',
+        '.mts'
+    ])
+};
+function getCollectionCount(collection) {
+    if (Array.isArray(collection)) return collection.length;
+    return collection.size;
+}
+function collectionIsEmpty(collection) {
+    return 0 === getCollectionCount(collection);
+}
+async function runCodemods(codemods, transformationPath, options) {
+    const globItems = await fast_glob.glob([
+        '**/*'
+    ], {
+        cwd: transformationPath
+    });
+    const results = {};
+    for (const codemod of codemods)results[codemod.name] = await runCodemod(codemod, transformationPath, globItems, options);
+    return results;
+}
+async function runCodemod(codemod, transformationPath, globItems, options) {
+    const { hooks, log: enableLogging, dry: runInDryMode } = defaultedOptions(options);
+    const extensions = new Set(Array.from(codemod.languages).reduce((acc, language)=>{
+        const mappedExtensions = LANG_TO_EXTENSIONS_MAPPING[language.toLowerCase()];
+        if (null == mappedExtensions) return acc;
+        return acc.concat(Array.from(mappedExtensions));
+    }, []));
+    const targets = globItems.filter((filepath)=>{
+        if (!hooks.targetFiltering(filepath)) return false;
+        const projectName = filepath.split('/')[0];
+        if (null == projectName) throw new Error('Invariant found, project name should be present');
+        return collectionIsEmpty(extensions) || extensions.has(node_path.extname(filepath));
+    });
+    if (0 === targets.length) return [];
+    if (enableLogging) console.log(`\u{1F9C9} '${codemod.name}' targeting ${targets.length} ${1 === targets.length ? 'file' : 'files'} to transform, chill and grab some mat\xe9`);
+    return Promise.all(targets.map(async (filepath)=>{
+        const fullPath = node_path.join(transformationPath, filepath);
+        try {
+            const content = await promises.readFile(fullPath, {
+                encoding: 'utf-8'
+            });
+            const modifications = await codemod.transformer(content, fullPath);
+            if (modifications.report.changesApplied > 0) {
+                const transformedContent = await hooks.postTransform(modifications.ast.root().text());
+                if (!runInDryMode) await promises.writeFile(fullPath, transformedContent);
+                if (enableLogging) console.log(`\u{1F680} finished '${codemod.name}'`, {
+                    filename: filepath,
+                    report: modifications.report
+                });
+            }
+            return ok(modifications);
+        } catch (error) {
+            if (enableLogging) console.error(`\u{274C} '${codemod.name}' failed to parse file`, filepath, error);
+            return err(error);
+        }
+    }));
+}
+function defaultedOptions(options) {
+    return {
+        hooks: defaultedHooks(options?.hooks),
+        log: options?.log ?? true,
+        dry: options?.dry ?? false
+    };
+}
+function defaultedHooks(hooks) {
+    const targetFiltering = hooks?.targetFiltering ?? (()=>true);
+    const postTransform = hooks?.postTransform ?? (async (content)=>content);
+    const preCodemodRun = hooks?.preCodemodRun ?? (async ()=>{});
+    return {
+        targetFiltering,
+        postTransform,
+        preCodemodRun
+    };
+}
+export { runCodemod, runCodemods };

package/dist/utils/collections.d.ts

@@ -0,0 +1,3 @@
+type AnyCollection = Array<unknown> | Set<unknown>;
+export declare function collectionIsEmpty<T extends AnyCollection>(collection: T): boolean;
+export {};

package/dist/utils/type-utils.d.ts

@@ -0,0 +1 @@
+export type Optional<T> = T | undefined | null;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kamaalio/codemod-kit",
+  "version": "0.0.1",
+  "type": "module",
+  "author": "Kamaal Farah",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ast-grep/napi": "^0.38.5",
+    "fast-glob": "^3.3.3",
+    "neverthrow": "^8.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@kamaalio/prettier-config": "^0.1.2",
+    "@rslib/core": "^0.10.2",
+    "@types/node": "^22.15.32",
+    "@vitest/coverage-v8": "3.2.4",
+    "eslint": "^9.29.0",
+    "globals": "^16.2.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.2",
+    "prettier": "^3.5.3",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.1",
+    "vitest": "^3.2.4"
+  },
+  "lint-staged": {
+    "**/*": "prettier --write --ignore-unknown"
+  },
+  "prettier": "@kamaalio/prettier-config",
+  "scripts": {
+    "build": "rslib build",
+    "build:clean": "rm -rf dist tsconfig.tsbuildinfo && pnpm run build",
+    "dev": "rslib build --watch",
+    "format": "prettier --write .",
+    "format:check": "prettier . --check",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "type-check": "tsc --noEmit"
+  }
+}