@clipboard-health/eslint-plugin 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @clipboard-health/eslint-plugin <!-- omit from toc -->
+
+Clipboard's [ESLint](https://eslint.org/) plugin.
+
+## Table of contents <!-- omit from toc -->
+
+- [Install](#install)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+> [!NOTE]
+> Take a look at our [eslint-config](https://github.com/ClipboardHealth/core-utils/tree/main/packages/eslint-config) which contains this plugin.
+> In most cases you can just use the eslint-config instead of directly installing this plugin.
+
+```bash
+npm install -D @clipboard-health/eslint-plugin
+```
+
+Then, modify your `.eslintrc.js` file to configure individual rules in this plugin:
+
+```js
+module.exports = {
+  plugins: ["@clipboard-health"],
+  overrides: [
+    {
+      files: ["**/*.controller.ts", "**/*.controllers.ts"],
+      rules: {
+        "@clipboard-health/enforce-ts-rest-in-controllers": "error",
+      },
+    },
+  ],
+  root: true,
+};
+```
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@clipboard-health/eslint-plugin",
+  "description": "Clipboard's ESLint Plugin",
+  "version": "0.1.0",
+  "dependencies": {
+    "@typescript-eslint/utils": "8.33.0",
+    "tslib": "2.8.1"
+  },
+  "keywords": [
+    "eslint",
+    "plugin"
+  ],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/eslint-plugin",
+    "type": "git",
+    "url": "git+https://github.com/ClipboardHealth/core-utils.git"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export declare const rules: {
+    "enforce-ts-rest-in-controllers": import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingDecorator" | "missingReturn" | "decoratorNotFromPackage" | "callNotFromPackage", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+};

package/src/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rules = void 0;
+const tslib_1 = require("tslib");
+const enforce_ts_rest_in_controllers_1 = tslib_1.__importDefault(require("./lib/rules/enforce-ts-rest-in-controllers"));
+exports.rules = {
+    "enforce-ts-rest-in-controllers": enforce_ts_rest_in_controllers_1.default,
+};
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/eslint-plugin/src/index.ts"],"names":[],"mappings":";;;;AAAA,wHAAoF;AAEvE,QAAA,KAAK,GAAG;IACnB,gCAAgC,EAAE,wCAA0B;CAC7D,CAAC"}

package/src/lib/createRule.d.ts

@@ -0,0 +1,3 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+declare const createRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener>;
+export default createRule;

package/src/lib/createRule.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/ClipboardHealth/core-utils/tree/main/packages/eslint-plugin/src/lib/rules/${name}`);
+exports.default = createRule;
+//# sourceMappingURL=createRule.js.map

package/src/lib/createRule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createRule.js","sourceRoot":"","sources":["../../../../../packages/eslint-plugin/src/lib/createRule.ts"],"names":[],"mappings":";;AAAA,oDAAuD;AAEvD,MAAM,UAAU,GAAG,mBAAW,CAAC,WAAW,CACxC,CAAC,IAAI,EAAE,EAAE,CACP,gGAAgG,IAAI,EAAE,CACzG,CAAC;AAEF,kBAAe,UAAU,CAAC"}

package/src/lib/rules/enforce-ts-rest-in-controllers/index.d.ts

@@ -0,0 +1,2 @@
+declare const rule: import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingDecorator" | "missingReturn" | "decoratorNotFromPackage" | "callNotFromPackage", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+export default rule;

package/src/lib/rules/enforce-ts-rest-in-controllers/index.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * @fileoverview Rule to require controller methods to use ts-rest as per our best practices on backend REST APIs
+ */
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = tslib_1.__importDefault(require("../../createRule"));
+const rule = (0, createRule_1.default)({
+    name: "enforce-ts-rest-in-controllers",
+    defaultOptions: [],
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require use of ts-rest on all controller methods",
+        },
+        schema: [],
+        messages: {
+            missingDecorator: "Controller method '{{name}}' must be decorated with `@TsRestHandler()` from `@ts-rest/nest` package. See https://www.notion.so/BP-REST-API-f769b7fe745c4cf38f6eca2e9ad8a843 for more information.",
+            missingReturn: "Controller method '{{name}}' must only return the result of calling `tsRestHandler()` from `@ts-rest/nest` package. See https://www.notion.so/BP-REST-API-f769b7fe745c4cf38f6eca2e9ad8a843 for more information.",
+            decoratorNotFromPackage: "Decorator `TsRestHandler` must be imported from `@ts-rest/nest`",
+            callNotFromPackage: "Method `tsRestHandler` must be imported from `@ts-rest/nest`",
+        },
+    },
+    create(context) {
+        let methodImportedCorrectly = false;
+        let decoratorImportedCorrectly = false;
+        return {
+            /*
+             * This method iterates through import declarations and verifies that the
+             * the `TsRestHandler` decorator and `tsRestHandler` method are imported
+             * from `@ts-rest/nest` package. We'll use this information to later
+             * highlight usages of those symbols to point out that they need to be
+             * imported from the correct source.
+             */
+            // eslint-disable-next-line sonarjs/cognitive-complexity
+            ImportDeclaration(node) {
+                if (node.source.value === "@ts-rest/nest") {
+                    for (const spec of node.specifiers) {
+                        if (spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                            if (spec.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                spec.imported.name === "tsRestHandler") {
+                                methodImportedCorrectly = true;
+                            }
+                            if (spec.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                spec.imported.name === "TsRestHandler") {
+                                decoratorImportedCorrectly = true;
+                            }
+                        }
+                    }
+                }
+            },
+            /*
+             * This method verifies that non-constructor and non-private methods use the
+             * `TsRestHandler` decorator and return the result of `tsRestHandler` as the
+             * only expression in it.
+             */
+            // eslint-disable-next-line sonarjs/cognitive-complexity, complexity
+            MethodDefinition(node) {
+                const symbolName = (node.key.type === utils_1.AST_NODE_TYPES.Identifier && node.key.name) || "<unknown>";
+                // Ignore this rule for constructor and private methods
+                if (node.kind === "constructor" ||
+                    node.accessibility === "private" ||
+                    (node.key.type === utils_1.AST_NODE_TYPES.Identifier && node.key.name === "constructor")) {
+                    return;
+                }
+                // Check for use of `@TsRestHandler()` decorator and ensure it comes from `@ts-rest/nest` package
+                const decorators = node.decorators || [];
+                const hasMatchingDecorator = decorators.some((decorator) => decorator.expression.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                    decorator.expression.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    decorator.expression.callee.name === "TsRestHandler");
+                if (!hasMatchingDecorator) {
+                    context.report({
+                        node,
+                        messageId: "missingDecorator",
+                        data: {
+                            name: symbolName,
+                        },
+                    });
+                }
+                decorators.forEach((decorator) => {
+                    if (decorator.expression.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                        decorator.expression.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        decorator.expression.callee.name === "TsRestHandler" &&
+                        !decoratorImportedCorrectly) {
+                        context.report({
+                            node: decorator,
+                            messageId: "decoratorNotFromPackage",
+                        });
+                    }
+                });
+                // Check for returning the result of `tsRestHandler()` method (without any other statement present), and ensure it comes from `@ts-rest/nest` package
+                const body = node.value?.body;
+                if (!body ||
+                    body.type !== utils_1.AST_NODE_TYPES.BlockStatement ||
+                    body.body.length !== 1 ||
+                    body.body[0]?.type !== utils_1.AST_NODE_TYPES.ReturnStatement) {
+                    context.report({
+                        node,
+                        messageId: "missingReturn",
+                        data: {
+                            name: symbolName,
+                        },
+                    });
+                    return;
+                }
+                const returnValueExpr = body.body[0].argument;
+                if (!returnValueExpr ||
+                    returnValueExpr.type !== utils_1.AST_NODE_TYPES.CallExpression ||
+                    returnValueExpr.callee.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    returnValueExpr.callee.name !== "tsRestHandler") {
+                    context.report({
+                        node,
+                        messageId: "missingReturn",
+                        data: {
+                            name: symbolName,
+                        },
+                    });
+                }
+                if (returnValueExpr &&
+                    returnValueExpr?.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                    returnValueExpr.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    returnValueExpr.callee.name === "tsRestHandler" &&
+                    !methodImportedCorrectly) {
+                    context.report({
+                        node: returnValueExpr,
+                        messageId: "callNotFromPackage",
+                    });
+                }
+            },
+        };
+    },
+});
+exports.default = rule;
+//# sourceMappingURL=index.js.map

package/src/lib/rules/enforce-ts-rest-in-controllers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../packages/eslint-plugin/src/lib/rules/enforce-ts-rest-in-controllers/index.ts"],"names":[],"mappings":"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"}