@tianjos/eslint-plugin-elegant 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thiago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @tianjos/eslint-plugin-elegant
+
+[![npm version](https://img.shields.io/npm/v/@tianjos/eslint-plugin-elegant.svg)](https://www.npmjs.com/package/@tianjos/eslint-plugin-elegant)
+[![license](https://img.shields.io/npm/l/@tianjos/eslint-plugin-elegant.svg)](./LICENSE)
+[![CI](https://github.com/tianjos/eslint-plugin-elegant/actions/workflows/ci.yml/badge.svg)](https://github.com/tianjos/eslint-plugin-elegant/actions/workflows/ci.yml)
+
+Opinionated ESLint rules for **elegant, behavior-rich TypeScript**. The plugin
+pushes code toward intention-revealing functions, honest types, and
+encapsulated domain models — the kind of constraints that pay off in NestJS
+services and DDD-style codebases.
+
+## Install
+
+```bash
+npm install --save-dev @tianjos/eslint-plugin-elegant
+```
+
+```bash
+pnpm add -D @tianjos/eslint-plugin-elegant
+```
+
+```bash
+yarn add -D @tianjos/eslint-plugin-elegant
+```
+
+### Peer dependencies
+
+This plugin does not bundle ESLint or the TypeScript toolchain. Install them
+alongside it:
+
+| Peer                          | Required version |
+| ----------------------------- | ---------------- |
+| `eslint`                      | `>=9`            |
+| `typescript`                  | `>=5`            |
+| `@typescript-eslint/parser`   | `>=8`            |
+
+```bash
+npm install --save-dev eslint typescript @typescript-eslint/parser
+```
+
+## Usage
+
+This plugin targets **flat config** (`eslint.config.mjs`). The fastest way to
+adopt it is to spread the `recommended` ruleset:
+
+```js
+// eslint.config.mjs
+import parser from '@typescript-eslint/parser';
+import elegant from '@tianjos/eslint-plugin-elegant';
+
+export default [
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser,
+      parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+    },
+    plugins: { elegant },
+    rules: {
+      ...elegant.configs.recommended.rules,
+    },
+  },
+];
+```
+
+A complete, copy-pasteable example (including test-file overrides) lives in
+[`eslint.config.example.mjs`](./eslint.config.example.mjs).
+
+## Rules
+
+The `recommended` config enables every custom rule plus the native
+[`max-params`](https://eslint.org/docs/latest/rules/max-params) rule.
+
+| Rule                                   | Source | What it catches                                                                 | `recommended` |
+| -------------------------------------- | ------ | ------------------------------------------------------------------------------- | ------------- |
+| `elegant/no-boolean-param`             | custom | Boolean parameters (flag arguments) on functions, methods, and constructors     | `error`       |
+| `elegant/max-class-methods`            | custom | Classes with more methods than the configured `max` (constructors excluded)     | `warn` (max 10) |
+| `elegant/no-type-assertion`            | custom | `value as T` and `<T>value` assertions (`as const` is allowed)                  | `error`       |
+| `elegant/no-null-return`               | custom | `return null` statements                                                        | `error`       |
+| `elegant/no-public-mutable-props`      | custom | Public, non-`readonly` class properties and public constructor parameter props  | `error`       |
+| `max-params`                           | native | Functions declaring more than `max` parameters                                  | `warn` (max 3) |
+
+### Rule details
+
+- **`no-boolean-param`** — a boolean argument almost always means the callee
+  does two things. Prefer two intention-revealing functions or an options
+  object. Flags both annotated (`flag: boolean`) and boolean-defaulted
+  (`flag = false`) parameters.
+- **`max-class-methods`** — a proxy for the Single Responsibility Principle.
+  Constructors are not counted; getters and setters are.
+- **`no-type-assertion`** — assertions silence the type checker. Reach for a
+  type guard, a generic, or a correctly typed value instead. `as const` is
+  permitted because it narrows rather than widens.
+- **`no-null-return`** — keeps absence out of return values; model it with an
+  explicit domain type or throw.
+- **`no-public-mutable-props`** — public state should be `readonly` so callers
+  cannot break an aggregate's invariants. `private`/`protected` members and
+  `readonly` members are allowed.
+
+## Configuration
+
+### Overriding thresholds
+
+`max-class-methods` and the native `max-params` both take a `max` option:
+
+```js
+rules: {
+  ...elegant.configs.recommended.rules,
+  'elegant/max-class-methods': ['warn', { max: 15 }],
+  'max-params': ['warn', { max: 4 }],
+}
+```
+
+### Relaxing rules in test files
+
+Tests routinely use flag arguments and larger fixtures. Add a second config
+block scoped to your spec globs:
+
+```js
+{
+  files: ['**/*.spec.ts', '**/*.test.ts', '**/*.e2e-spec.ts'],
+  rules: {
+    'elegant/no-boolean-param': 'off',
+    'elegant/max-class-methods': 'off',
+    'max-params': 'off',
+  },
+}
+```
+
+## Compatibility
+
+The package ships a single CommonJS build that is consumable as both
+`require('@tianjos/eslint-plugin-elegant')` and an ESM
+`import elegant from '@tianjos/eslint-plugin-elegant'`. The exported object
+exposes `{ meta, rules, configs }`.
+
+## License
+
+[MIT](./LICENSE) © Thiago

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+declare const rules: {
+    'no-boolean-param': TSESLint.RuleModule<"booleanParam", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'max-class-methods': TSESLint.RuleModule<"tooManyMethods", [{
+        max: number;
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-type-assertion': TSESLint.RuleModule<"noAssertion", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-null-return': TSESLint.RuleModule<"noNullReturn", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-public-mutable-props': TSESLint.RuleModule<"mutableProp", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+};
+type Plugin = {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: typeof rules;
+    configs: Record<string, TSESLint.FlatConfig.Config>;
+    /**
+     * Self-reference so the package resolves identically whether consumers reach
+     * it via `require('...')`, `require('...').default`, or an ESM
+     * `import elegant from '...'`. This sidesteps the CJS/ESM interop hazard.
+     */
+    default?: Plugin;
+};
+declare const plugin: Plugin;
+export = plugin;

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const max_class_methods_1 = __importDefault(require("./rules/max-class-methods"));
+const no_boolean_param_1 = __importDefault(require("./rules/no-boolean-param"));
+const no_null_return_1 = __importDefault(require("./rules/no-null-return"));
+const no_public_mutable_props_1 = __importDefault(require("./rules/no-public-mutable-props"));
+const no_type_assertion_1 = __importDefault(require("./rules/no-type-assertion"));
+const { name, version } = require('../package.json');
+const rules = {
+    'no-boolean-param': no_boolean_param_1.default,
+    'max-class-methods': max_class_methods_1.default,
+    'no-type-assertion': no_type_assertion_1.default,
+    'no-null-return': no_null_return_1.default,
+    'no-public-mutable-props': no_public_mutable_props_1.default,
+};
+const plugin = {
+    meta: { name, version },
+    rules,
+    configs: {},
+};
+plugin.configs.recommended = {
+    name: 'elegant/recommended',
+    plugins: { elegant: plugin },
+    rules: {
+        'elegant/no-boolean-param': 'error',
+        'elegant/max-class-methods': ['warn', { max: 10 }],
+        'elegant/no-type-assertion': 'error',
+        'elegant/no-null-return': 'error',
+        'elegant/no-public-mutable-props': 'error',
+        'max-params': ['warn', { max: 3 }],
+    },
+};
+plugin.default = plugin;
+module.exports = plugin;

package/dist/rules/max-class-methods.d.ts

@@ -0,0 +1,7 @@
+type Options = [{
+    max: number;
+}];
+declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"tooManyMethods", Options, unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default _default;

package/dist/rules/max-class-methods.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_MAX = 10;
+exports.default = (0, createRule_1.createRule)({
+    name: 'max-class-methods',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce a maximum number of methods per class to keep classes cohesive and single-purpose.',
+        },
+        messages: {
+            tooManyMethods: "Class '{{name}}' has {{count}} methods (max {{max}}). Consider splitting its responsibilities.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: { type: 'integer', minimum: 1 },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ max: DEFAULT_MAX }],
+    create(context, [{ max }]) {
+        return {
+            ClassBody(node) {
+                const methods = node.body.filter((member) => member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+                    member.kind !== 'constructor');
+                if (methods.length <= max) {
+                    return;
+                }
+                const classNode = node.parent;
+                const name = classNode.id?.name ?? '(anonymous)';
+                context.report({
+                    node: classNode.id ?? node,
+                    messageId: 'tooManyMethods',
+                    data: { name, count: methods.length, max },
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-boolean-param.d.ts

@@ -0,0 +1,4 @@
+declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"booleanParam", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default _default;

package/dist/rules/no-boolean-param.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const isBooleanAnnotation = (annotation) => annotation?.type === utils_1.AST_NODE_TYPES.TSBooleanKeyword;
+const isBooleanLiteral = (node) => node.type === utils_1.AST_NODE_TYPES.Literal && typeof node.value === 'boolean';
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-boolean-param',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow boolean parameters, which are flag arguments signalling a function that does more than one thing.',
+        },
+        messages: {
+            booleanParam: "Boolean parameter '{{name}}' is a flag argument. Prefer two intention-revealing functions or an options object.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const checkParam = (param) => {
+            const target = param.type === utils_1.AST_NODE_TYPES.TSParameterProperty
+                ? param.parameter
+                : param;
+            let name;
+            let annotation;
+            let defaultsToBoolean = false;
+            if (target.type === utils_1.AST_NODE_TYPES.Identifier) {
+                name = target;
+                annotation = target.typeAnnotation?.typeAnnotation;
+            }
+            else if (target.type === utils_1.AST_NODE_TYPES.AssignmentPattern &&
+                target.left.type === utils_1.AST_NODE_TYPES.Identifier) {
+                name = target.left;
+                annotation = target.left.typeAnnotation?.typeAnnotation;
+                defaultsToBoolean = isBooleanLiteral(target.right);
+            }
+            if (!name) {
+                return;
+            }
+            if (isBooleanAnnotation(annotation) || defaultsToBoolean) {
+                context.report({
+                    node: name,
+                    messageId: 'booleanParam',
+                    data: { name: name.name },
+                });
+            }
+        };
+        const checkFunction = (node) => {
+            node.params.forEach(checkParam);
+        };
+        return {
+            FunctionDeclaration: checkFunction,
+            FunctionExpression: checkFunction,
+            ArrowFunctionExpression: checkFunction,
+        };
+    },
+});

package/dist/rules/no-null-return.d.ts

@@ -0,0 +1,4 @@
+declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noNullReturn", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default _default;

package/dist/rules/no-null-return.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-null-return',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow returning null. Model absence with an explicit type, an Optional/Maybe, or by throwing.',
+        },
+        messages: {
+            noNullReturn: 'Returning null leaks absence into callers. Return an explicit empty value, a domain type, or throw.',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            ReturnStatement(node) {
+                const { argument } = node;
+                if (argument?.type === utils_1.AST_NODE_TYPES.Literal &&
+                    argument.value === null &&
+                    argument.raw === 'null') {
+                    context.report({ node, messageId: 'noNullReturn' });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-public-mutable-props.d.ts

@@ -0,0 +1,4 @@
+declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"mutableProp", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default _default;

package/dist/rules/no-public-mutable-props.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const isHidden = (accessibility) => accessibility === 'private' || accessibility === 'protected';
+const keyName = (key) => {
+    if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    if (key.type === utils_1.AST_NODE_TYPES.Literal) {
+        return String(key.value);
+    }
+    return 'property';
+};
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-public-mutable-props',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow public mutable class properties. Public state should be readonly to protect invariants and preserve encapsulation.',
+        },
+        messages: {
+            mutableProp: "Public property '{{name}}' is mutable. Make it readonly or expose it through a method that protects the invariant.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            PropertyDefinition(node) {
+                if (node.readonly || isHidden(node.accessibility)) {
+                    return;
+                }
+                context.report({
+                    node: node.key,
+                    messageId: 'mutableProp',
+                    data: { name: keyName(node.key) },
+                });
+            },
+            TSParameterProperty(node) {
+                // Only constructor parameter properties carry an accessibility modifier.
+                if (node.accessibility !== 'public' ||
+                    node.readonly) {
+                    return;
+                }
+                const target = node.parameter.type === utils_1.AST_NODE_TYPES.AssignmentPattern
+                    ? node.parameter.left
+                    : node.parameter;
+                if (target.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    return;
+                }
+                context.report({
+                    node: target,
+                    messageId: 'mutableProp',
+                    data: { name: target.name },
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-type-assertion.d.ts

@@ -0,0 +1,4 @@
+declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noAssertion", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default _default;

package/dist/rules/no-type-assertion.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const isAsConst = (node) => node.typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+    node.typeAnnotation.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+    node.typeAnnotation.typeName.name === 'const';
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-type-assertion',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow type assertions, which bypass the type checker. Prefer type guards, generics, or honest types. `as const` is allowed.',
+        },
+        messages: {
+            noAssertion: 'Type assertions silence the type checker. Use a type guard, a generic, or a correctly typed value instead.',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            TSAsExpression(node) {
+                if (isAsConst(node)) {
+                    return;
+                }
+                context.report({ node, messageId: 'noAssertion' });
+            },
+            TSTypeAssertion(node) {
+                context.report({ node, messageId: 'noAssertion' });
+            },
+        };
+    },
+});

package/dist/utils/createRule.d.ts

@@ -0,0 +1,8 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+/**
+ * Factory for all rules in this plugin. Centralises the docs URL convention so
+ * every rule links back to its documentation by name.
+ */
+export 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> & {
+    name: string;
+};

package/dist/utils/createRule.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRule = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+/**
+ * Factory for all rules in this plugin. Centralises the docs URL convention so
+ * every rule links back to its documentation by name.
+ */
+exports.createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/tianjos/eslint-plugin-elegant/blob/main/docs/rules/${name}.md`);

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@tianjos/eslint-plugin-elegant",
+  "version": "0.1.0",
+  "description": "Opinionated ESLint rules for elegant, behavior-rich TypeScript: no flag arguments, no type assertions, no null returns, no public mutable state, and small focused classes.",
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "typescript",
+    "nestjs",
+    "code-quality",
+    "linting"
+  ],
+  "author": "Thiago <thiago@bullcredtech.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/tianjos/eslint-plugin-elegant#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tianjos/eslint-plugin-elegant.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tianjos/eslint-plugin-elegant/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "jest",
+    "release": "standard-version",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@typescript-eslint/parser": ">=8",
+    "eslint": ">=9",
+    "typescript": ">=5"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/rule-tester": "^8.0.0",
+    "@typescript-eslint/utils": "^8.0.0",
+    "eslint": "^9.0.0",
+    "jest": "^29.7.0",
+    "standard-version": "^9.5.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}