@tianjos/eslint-plugin-elegant 0.3.1 → 0.4.0

package/README.md

@@ -68,13 +68,16 @@ A complete, copy-pasteable example (including test-file overrides) lives in
 
 ## Rules
 
-The `recommended` config enables every custom rule plus the native
-[`max-params`](https://eslint.org/docs/latest/rules/max-params) rule.
+The `recommended` config enables every custom rule plus two native ones,
+[`max-params`](https://eslint.org/docs/latest/rules/max-params) and
+[`no-else-return`](https://eslint.org/docs/latest/rules/no-else-return).
 
 | 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/max-class-dependencies`       | custom | Classes depending on more distinct collaborators than `max` (constructor injections plus `new`) | `warn` (max 4) |
+| `elegant/max-class-fields`             | custom | Classes holding more instance fields than `max` (declared fields plus parameter properties) | `warn` (max 5) |
 | `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`       |
@@ -83,62 +86,304 @@ The `recommended` config enables every custom rule plus the native
 | `elegant/no-instanceof`                | custom | Use of the `instanceof` operator                                                | `error`       |
 | `elegant/no-static-members`            | custom | Static methods, properties, accessors, and blocks (`allowReadonly` to permit constants) | `error` |
 | `elegant/no-null`                      | custom | The `null` literal as a value (type annotations and direct `return null` excepted) | `error`     |
+| `elegant/no-comments-in-function-body` | custom | Comments inside function bodies (directives and empty blocks excepted)          | `error`       |
+| `elegant/no-else-after-throw`          | custom | An `else` branch when the `then` branch always throws                           | `error`       |
+| `elegant/no-interpolated-log-message`  | custom | Log messages built by interpolation or concatenation                            | `error`       |
+| `elegant/max-returns`                  | custom | Functions returning from more places than `max`                                 | `warn` (max 3) |
 | `max-params`                           | native | Functions declaring more than `max` parameters                                  | `warn` (max 3) |
+| `no-else-return`                       | native | An `else` branch when the `then` branch always returns (`allowElseIf: false`)   | `error`       |
 
 ### 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.
-- **`no-logic-in-constructor`** — a constructor should only wire arguments to
-  fields. Validation, transformation, and I/O belong in a static factory or a
-  method, keeping object construction predictable. Parameter properties
-  (`constructor(private readonly x: T)`) and a leading `super(...)` are allowed;
-  computed right-hand sides (`this.x = x * 2`, `this.items = items.slice()`) and
-  any non-assignment statement are flagged.
-- **`no-getters-setters`** — getters and setters turn objects into data bags;
-  prefer methods that expose behavior. Native `get`/`set` accessors (and
-  `accessor` fields) are always flagged. The opt-in `{ methods: true }` option
-  also flags conventional `getX`/`setX` methods — useful for strict Elegant
-  Objects style, but noisy around repositories and framework hooks, so it stays
-  off in `recommended`.
-- **`no-instanceof`** — `instanceof` is type discrimination that belongs inside a
-  polymorphic method on the object. Pairs with `no-type-assertion` to keep
-  type-based branching out of the codebase.
-- **`no-static-members`** — static state and behavior cannot be injected,
-  substituted, or mocked. Prefer instances (with dependency injection) and a
-  module-level `const` for shared values. The `{ allowReadonly: true }` option
-  permits `static readonly` constants. Note this also flags `static` factory
-  methods (`static create()`), which are common; relax per-file if your design
-  relies on them.
-- **`no-null`** — completes `no-null-return` by banning the `null` literal as a
-  value everywhere (`const x = null`, `x === null`, `fn(null)`), pushing absence
-  into explicit types or `undefined`. `null` in type positions (`string | null`)
-  and a direct `return null` (owned by `no-null-return`) are left alone. This is
-  strict and will flag idioms like `JSON.stringify(x, null, 2)` — relax it in the
-  files where you interoperate with null-based APIs.
+#### `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. Configurable via `{ max: number }` (default `10`).
+
+#### `max-class-dependencies`
+
+The coupling counterpart to `max-class-methods`: a class that needs six
+collaborators to do its job is coordinating, not modelling. Counts the distinct
+types annotated on constructor parameters plus every type instantiated with
+`new` inside the class body — so a dependency hidden behind `new HttpClient()`
+weighs the same as an injected one.
+
+De-duplication keeps type arguments, so `Repository<Order>` and
+`Repository<Customer>` count as two collaborators while the same `Clock`
+injected twice counts as one. Nested classes are budgeted independently of their
+host.
+
+Three things never count: primitives and inline types (they are not type
+references), a default list of ambient built-ins (`Date`, `Map`, `Set`,
+`Promise`, `Error`, `Array`, `RegExp`, `URL`, `WeakMap`, `WeakSet`), and
+exceptions raised with `throw new ...`. That last exclusion is what makes the
+rule usable in NestJS, where `throw new NotFoundException()` is routine and says
+nothing about a class's design.
+
+Configurable via `{ max: number, ignore: string[] }` (default `max: 4`).
+`ignore` adds to the built-in list — reach for it when an ambient concern such
+as `Logger` or `ConfigService` is in every constructor and you would rather not
+budget for it:
+
+```js
+'elegant/max-class-dependencies': ['warn', { max: 4, ignore: ['Logger'] }],
+```
+
+#### `max-class-fields`
+
+The third axis of class size, after methods and collaborators: a class carrying
+a dozen fields is a record with a namespace, not a model. Counts instance fields
+declared in the body — plain, `abstract`, or `accessor` — plus every constructor
+parameter property. Methods and accessors belong to `max-class-methods`, and
+`static` members to `no-static-members`, so neither is counted here.
+
+Decorated properties are skipped by default. `@Column`, `@IsString` and
+`@ApiProperty` map a field to a table or a payload, so a DTO or an ORM entity
+declares one field per column by design and has no business inside a budget:
+
+```ts
+class CreateOrderDto {
+  @IsString() customerId: string; // not counted
+  @IsInt() quantity: number; // not counted
+}
+```
+
+**The exemption stops at the constructor.** A decorator on a parameter is
+injection, not mapping, so `@Inject(TOKEN) private readonly repo: Repo` stays
+inside the budget — otherwise a service wired entirely through tokens would
+count zero fields, which is exactly the class the rule exists to catch. Set
+`{ ignoreDecorated: false }` to budget mapped properties too.
+
+Configurable via `{ max: number, ignoreDecorated: boolean }` (default `max: 5`,
+`ignoreDecorated: true`). The default leaves room for the four collaborators
+`max-class-dependencies` allows plus one field of genuine state; past that the
+two rules deliberately overlap, because a class over both budgets is over-sized
+on both axes.
+
+#### `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.
+
+#### `no-logic-in-constructor`
+
+A constructor should only wire arguments to fields. Validation, transformation,
+and I/O belong in a static factory or a method, keeping object construction
+predictable. Parameter properties (`constructor(private readonly x: T)`) and a
+leading `super(...)` are allowed; computed right-hand sides (`this.x = x * 2`,
+`this.items = items.slice()`) and any non-assignment statement are flagged.
+
+#### `no-getters-setters`
+
+Getters and setters turn objects into data bags; prefer methods that expose
+behavior. Native `get`/`set` accessors (and `accessor` fields) are always
+flagged. The opt-in `{ methods: true }` option also flags conventional
+`getX`/`setX` methods — useful for strict Elegant Objects style, but noisy
+around repositories and framework hooks, so it stays off in `recommended`.
+
+#### `no-instanceof`
+
+`instanceof` is type discrimination that belongs inside a polymorphic method on
+the object. Pairs with `no-type-assertion` to keep type-based branching out of
+the codebase.
+
+#### `no-static-members`
+
+Static state and behavior cannot be injected, substituted, or mocked. Prefer
+instances (with dependency injection) and a module-level `const` for shared
+values. The `{ allowReadonly: true }` option permits `static readonly`
+constants. Note this also flags `static` factory methods (`static create()`),
+which are common; relax per-file if your design relies on them.
+
+#### `no-null`
+
+Completes `no-null-return` by banning the `null` literal as a value everywhere
+(`const x = null`, `x === null`, `fn(null)`), pushing absence into explicit types
+or `undefined`. `null` in type positions (`string | null`) and a direct
+`return null` (owned by `no-null-return`) are left alone. This is strict and will
+flag idioms like `JSON.stringify(x, null, 2)` — relax it in the files where you
+interoperate with null-based APIs.
+
+#### `no-comments-in-function-body`
+
+A comment inside a body is usually a name that never got written: it labels a
+run of statements that wanted to be its own function. Move the explanation to a
+docblock above the function, or extract what it describes and let the call read
+as the sentence the comment was trying to be.
+
+Applies to every function with a block body — methods, constructors, function
+declarations, and arrow functions. Comments outside a body are untouched, so
+docblocks, module-level notes, and comments between class members are fine. Each
+comment is attributed to the innermost function containing it, so one in a
+nested arrow is reported once, against that arrow.
+
+Two things are never reported:
+
+- **Directives**, which the toolchain reads rather than a human:
+  `eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `prettier-ignore`,
+  `istanbul ignore`, `c8 ignore`, `v8 ignore`, `webpackChunkName`,
+  `@vite-ignore`. Extend the list with `{ allow: string[] }` for project
+  conventions such as `@codegen`.
+- **Comments alone in an empty block**, where there is no code to name and the
+  comment is the only thing explaining the silence. The check looks at the
+  innermost block, not the function, so an empty `catch` keeps its note even
+  inside a busy function:
+
+```ts
+function run(): void {
+  try {
+    go();
+  } catch {
+    // the failure is expected here
+  }
+}
+```
+
+#### `no-else-after-throw`
+
+When the `then` branch throws, control never reaches what follows, so `else`
+carries no information and only deepens nesting. Drop it and let the alternative
+sit at the outer level, where it reads as the normal path rather than one of two
+symmetric cases:
+
+```ts
+// before
+if (amount < 0) {
+  throw new NegativeAmount(amount);
+} else {
+  process(amount);
+}
+
+// after
+if (amount < 0) {
+  throw new NegativeAmount(amount);
+}
+process(amount);
+```
+
+A branch counts as always throwing when it is a bare `throw` or a block whose
+**last** statement is one. The check does not recurse, which is deliberate: a
+block ending in a nested `if` may or may not throw, and there `else` still says
+something.
+
+`else if` is flagged too, since the same rewrite applies. The rule has no
+options and no autofix — dedenting a block reliably is the formatter's job, not
+a linter's.
+
+Its sibling for `return` is the native
+[`no-else-return`](https://eslint.org/docs/latest/rules/no-else-return), which
+`recommended` enables with `allowElseIf: false` to match. Prefer the native
+rule's defaults? Override it in one line:
+
+```js
+'no-else-return': 'error',
+```
+
+#### `no-interpolated-log-message`
+
+A log message should be a constant, with everything that varies passed as
+structured data. This is not a style preference: `` `order ${id} confirmed` ``
+produces one distinct message per order, which no aggregator can group, and it
+buries `id` inside prose instead of leaving it as a field you can filter on.
+
+```ts
+// before — N messages, and the id is not queryable
+this.logger.log(`order ${id} confirmed for ${customer}`);
+
+// after — one message, two fields
+this.logger.log('order confirmed', { orderId: id, customer });
+```
+
+The rule looks only at the **message argument**, which it takes to be the first
+argument that is not an object literal. That lands on the message under either
+convention — `info(message, data)` as in NestJS and winston, `info(data,
+message)` as in pino — so the rule never dictates where your data goes. An
+interpolated *later* argument is left alone, since that position is context
+rather than the message.
+
+Flagged: template literals with expressions, and `+` concatenation. A plain
+identifier passes, so `logger.info(message)` is fine — chasing that would need
+type information, which no rule in this plugin requires.
+
+A call counts as logging when the method is a level (`log`, `info`, `warn`,
+`error`, `debug`, `verbose`, `trace`, `fatal`) and the receiver is named `logger`
+or `log`, whether local or a field (`this.logger.info`). Both lists are widened
+with `{ objects: string[], methods: string[] }`:
+
+```js
+'elegant/no-interpolated-log-message': ['error', { objects: ['audit'] }],
+```
+
+**Known limitation.** When the first argument is an identifier, it is taken for
+the message, so pino's error form slips through:
+
+```ts
+logger.error(err, `order ${id} failed`); // not reported
+```
+
+Telling that apart from `logger.info(message)` needs type information. The case
+is pinned by a test so the behaviour is deliberate rather than accidental.
+
+#### `max-returns`
+
+A port of Checkstyle's `ReturnCount`, but not of its threshold. qulice sets it
+to `1` — a single exit — which reads well in Java and badly here, because it
+outlaws the guard clause that `no-else-after-throw` in this very preset pushes
+you towards. Two rules in one config should not disagree.
+
+At `max: 3` the rule stops arguing about single exit and measures sprawl
+instead. Two or three guards followed by a final `return` pass; a function
+leaving from six different places is the one worth splitting.
+
+```ts
+// passes — idiomatic guards
+function charge(amount: number): number {
+  if (amount < 0) return 0;
+  if (amount > limit) return limit;
+  return amount;
+}
+```
+
+Every function gets its own budget, so a callback's exits are never charged to
+the function hosting it. Bare `return;` counts — leaving early is leaving,
+value or not. An arrow with an expression body has no `return` statement at all
+and never trips the rule.
+
+Functions are reported by the name that binds them — a declaration's own, a
+method's key, or the `const` or class field holding an arrow — falling back to
+`(anonymous)` for an inline callback. Configurable via `{ max: number }`
+(default `3`).
 
 ## Configuration
 
 ### Overriding thresholds
 
-`max-class-methods` and the native `max-params` both take a `max` option:
+`max-class-methods`, `max-class-dependencies`, `max-class-fields`, and the
+native `max-params` all take a `max` option:
 
 ```js
 rules: {
   ...elegant.configs.recommended.rules,
   'elegant/max-class-methods': ['warn', { max: 15 }],
+  'elegant/max-class-dependencies': ['warn', { max: 6 }],
+  'elegant/max-class-fields': ['warn', { max: 8 }],
   'max-params': ['warn', { max: 4 }],
 }
 ```
@@ -154,6 +399,9 @@ block scoped to your spec globs:
   rules: {
     'elegant/no-boolean-param': 'off',
     'elegant/max-class-methods': 'off',
+    'elegant/max-class-dependencies': 'off',
+    'elegant/max-class-fields': 'off',
+    'elegant/no-comments-in-function-body': 'off',
     'max-params': 'off',
   },
 }
@@ -166,6 +414,19 @@ The package ships a single CommonJS build that is consumable as both
 `import elegant from '@tianjos/eslint-plugin-elegant'`. The exported object
 exposes `{ meta, rules, configs }`.
 
+## Prior art
+
+This plugin is a TypeScript adaptation of [Elegant Objects](https://www.elegantobjects.org/)
+(Yegor Bugayenko) and [qulice](https://github.com/yegor256/qulice) — the Java
+quality enforcer that codifies those principles on top of Checkstyle and PMD.
+Rules such as `no-logic-in-constructor` (qulice's `ConstructorsCodeFreeCheck`),
+`max-class-dependencies` (Checkstyle's `ClassDataAbstractionCoupling`),
+`max-class-fields` (PMD's `TooManyFields`),
+`no-comments-in-function-body` (`MethodBodyCommentsCheck`), `no-null`,
+`no-getters-setters`, and `no-static-members` are ports of that
+philosophy. The concepts are reimplemented from scratch against the TypeScript
+AST; no qulice code is used.
+
 ## License
 
 [MIT](./LICENSE) © Thiago

package/dist/index.d.ts

@@ -8,6 +8,18 @@ declare const rules: {
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };
+    'max-class-dependencies': TSESLint.RuleModule<"tooManyDependencies", [{
+        max: number;
+        ignore: string[];
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'max-class-fields': TSESLint.RuleModule<"tooManyFields", [{
+        max: number;
+        ignoreDecorated: boolean;
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
     'no-type-assertion': TSESLint.RuleModule<"noAssertion", [], unknown, TSESLint.RuleListener> & {
         name: string;
     };
@@ -36,6 +48,25 @@ declare const rules: {
     'no-null': TSESLint.RuleModule<"noNull", [], unknown, TSESLint.RuleListener> & {
         name: string;
     };
+    'no-comments-in-function-body': TSESLint.RuleModule<"commentInBody", [{
+        allow: string[];
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-else-after-throw': TSESLint.RuleModule<"elseAfterThrow", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-interpolated-log-message': TSESLint.RuleModule<"interpolatedMessage", [{
+        objects: string[];
+        methods: string[];
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'max-returns': TSESLint.RuleModule<"tooManyReturns", [{
+        max: number;
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
 };
 type Plugin = {
     meta: {

package/dist/index.js

@@ -2,10 +2,16 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+const max_class_dependencies_1 = __importDefault(require("./rules/max-class-dependencies"));
+const max_class_fields_1 = __importDefault(require("./rules/max-class-fields"));
+const max_returns_1 = __importDefault(require("./rules/max-returns"));
 const max_class_methods_1 = __importDefault(require("./rules/max-class-methods"));
 const no_boolean_param_1 = __importDefault(require("./rules/no-boolean-param"));
+const no_comments_in_function_body_1 = __importDefault(require("./rules/no-comments-in-function-body"));
+const no_else_after_throw_1 = __importDefault(require("./rules/no-else-after-throw"));
 const no_getters_setters_1 = __importDefault(require("./rules/no-getters-setters"));
 const no_instanceof_1 = __importDefault(require("./rules/no-instanceof"));
+const no_interpolated_log_message_1 = __importDefault(require("./rules/no-interpolated-log-message"));
 const no_logic_in_constructor_1 = __importDefault(require("./rules/no-logic-in-constructor"));
 const no_null_1 = __importDefault(require("./rules/no-null"));
 const no_null_return_1 = __importDefault(require("./rules/no-null-return"));
@@ -16,6 +22,8 @@ const { name, version } = require('../package.json');
 const rules = {
     'no-boolean-param': no_boolean_param_1.default,
     'max-class-methods': max_class_methods_1.default,
+    'max-class-dependencies': max_class_dependencies_1.default,
+    'max-class-fields': max_class_fields_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,
@@ -24,6 +32,10 @@ const rules = {
     'no-instanceof': no_instanceof_1.default,
     'no-static-members': no_static_members_1.default,
     'no-null': no_null_1.default,
+    'no-comments-in-function-body': no_comments_in_function_body_1.default,
+    'no-else-after-throw': no_else_after_throw_1.default,
+    'no-interpolated-log-message': no_interpolated_log_message_1.default,
+    'max-returns': max_returns_1.default,
 };
 const plugin = {
     meta: { name, version },
@@ -36,6 +48,9 @@ plugin.configs.recommended = {
     rules: {
         'elegant/no-boolean-param': 'error',
         'elegant/max-class-methods': ['warn', { max: 10 }],
+        'elegant/max-class-dependencies': ['warn', { max: 4 }],
+        'elegant/max-class-fields': ['warn', { max: 5 }],
+        'elegant/max-returns': ['warn', { max: 3 }],
         'elegant/no-type-assertion': 'error',
         'elegant/no-null-return': 'error',
         'elegant/no-public-mutable-props': 'error',
@@ -44,7 +59,11 @@ plugin.configs.recommended = {
         'elegant/no-instanceof': 'error',
         'elegant/no-static-members': 'error',
         'elegant/no-null': 'error',
+        'elegant/no-comments-in-function-body': 'error',
+        'elegant/no-else-after-throw': 'error',
+        'elegant/no-interpolated-log-message': 'error',
         'max-params': ['warn', { max: 3 }],
+        'no-else-return': ['error', { allowElseIf: false }],
     },
 };
 plugin.default = plugin;

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

@@ -0,0 +1,9 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type Options = [{
+    max: number;
+    ignore: string[];
+}];
+declare const _default: TSESLint.RuleModule<"tooManyDependencies", Options, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default _default;

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

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_MAX = 4;
+/**
+ * Ambient types every codebase reaches for. Instantiating a `Date` or a `Map` is
+ * not a design decision worth budgeting, so they never count as collaborators.
+ */
+const BUILT_INS = [
+    'Array',
+    'Date',
+    'Error',
+    'Map',
+    'Promise',
+    'RegExp',
+    'Set',
+    'URL',
+    'WeakMap',
+    'WeakSet',
+];
+const injected = (body, sourceCode) => {
+    const constructor = body.body.find((member) => member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+        member.kind === 'constructor');
+    return (constructor?.value.params ?? []).flatMap((param) => {
+        const target = param.type === utils_1.AST_NODE_TYPES.TSParameterProperty
+            ? param.parameter
+            : param;
+        const annotation = target.typeAnnotation?.typeAnnotation;
+        return annotation?.type === utils_1.AST_NODE_TYPES.TSTypeReference
+            ? [
+                {
+                    key: sourceCode.getText(annotation),
+                    root: sourceCode.getText(annotation.typeName),
+                },
+            ]
+            : [];
+    });
+};
+const instantiated = (node, sourceCode) => {
+    const root = sourceCode.getText(node.callee);
+    const args = node.typeArguments;
+    return {
+        key: `${root}${args === undefined ? '' : sourceCode.getText(args)}`,
+        root,
+    };
+};
+exports.default = (0, createRule_1.createRule)({
+    name: 'max-class-dependencies',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce a maximum number of distinct collaborators a class depends on.',
+        },
+        messages: {
+            tooManyDependencies: "Class '{{name}}' depends on {{count}} types (max {{max}}): {{names}}. Consider extracting a collaborator.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: { type: 'integer', minimum: 1 },
+                    ignore: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ max: DEFAULT_MAX, ignore: [] }],
+    create(context, [{ max, ignore }]) {
+        const sourceCode = context.sourceCode;
+        const ignored = new Set([...BUILT_INS, ...ignore]);
+        const scopes = [];
+        const record = (scope, dependency) => {
+            if (scope !== undefined && !ignored.has(dependency.root)) {
+                scope.add(dependency.key);
+            }
+        };
+        return {
+            ClassBody(node) {
+                const scope = new Set();
+                scopes.push(scope);
+                for (const dependency of injected(node, sourceCode)) {
+                    record(scope, dependency);
+                }
+            },
+            NewExpression(node) {
+                if (node.parent.type === utils_1.AST_NODE_TYPES.ThrowStatement) {
+                    return;
+                }
+                record(scopes[scopes.length - 1], instantiated(node, sourceCode));
+            },
+            'ClassBody:exit'(node) {
+                const dependencies = scopes.pop() ?? new Set();
+                if (dependencies.size <= max) {
+                    return;
+                }
+                const classNode = node.parent;
+                context.report({
+                    node: classNode.id ?? node,
+                    messageId: 'tooManyDependencies',
+                    data: {
+                        name: classNode.id?.name ?? '(anonymous)',
+                        count: dependencies.size,
+                        max,
+                        names: [...dependencies].join(', '),
+                    },
+                });
+            },
+        };
+    },
+});

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

@@ -0,0 +1,9 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type Options = [{
+    max: number;
+    ignoreDecorated: boolean;
+}];
+declare const _default: TSESLint.RuleModule<"tooManyFields", Options, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default _default;

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

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_MAX = 5;
+const isField = (member) => member.type === utils_1.AST_NODE_TYPES.PropertyDefinition ||
+    member.type === utils_1.AST_NODE_TYPES.TSAbstractPropertyDefinition ||
+    member.type === utils_1.AST_NODE_TYPES.AccessorProperty;
+const named = (key, sourceCode) => key.type === utils_1.AST_NODE_TYPES.Identifier ? key.name : sourceCode.getText(key);
+/**
+ * Properties declared in the class body. A decorated one is skipped by default:
+ * `@Column`, `@IsString` and friends map a field to a table or a payload, which
+ * is framework shape rather than state the class chose to carry.
+ */
+const declared = (member, sourceCode, ignoreDecorated) => isField(member) &&
+    !member.static &&
+    !(ignoreDecorated && member.decorators.length > 0)
+    ? [named(member.key, sourceCode)]
+    : [];
+/**
+ * Constructor parameter properties. `ignoreDecorated` deliberately does not
+ * reach them: a decorator on a parameter is injection (`@Inject(TOKEN)`), so the
+ * field is a genuine collaborator and has to stay inside the budget.
+ */
+const promoted = (member, sourceCode) => {
+    if (member.type !== utils_1.AST_NODE_TYPES.MethodDefinition ||
+        member.kind !== 'constructor') {
+        return [];
+    }
+    return member.value.params.flatMap((param) => param.type === utils_1.AST_NODE_TYPES.TSParameterProperty
+        ? [named(param.parameter, sourceCode)]
+        : []);
+};
+exports.default = (0, createRule_1.createRule)({
+    name: 'max-class-fields',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce a maximum number of instance fields per class to keep objects from becoming data bags.',
+        },
+        messages: {
+            tooManyFields: "Class '{{name}}' holds {{count}} fields (max {{max}}): {{names}}. Consider grouping related fields into a value object.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: { type: 'integer', minimum: 1 },
+                    ignoreDecorated: { type: 'boolean' },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ max: DEFAULT_MAX, ignoreDecorated: true }],
+    create(context, [{ max, ignoreDecorated }]) {
+        const sourceCode = context.sourceCode;
+        return {
+            ClassBody(node) {
+                const fields = node.body.flatMap((member) => [
+                    ...declared(member, sourceCode, ignoreDecorated),
+                    ...promoted(member, sourceCode),
+                ]);
+                if (fields.length <= max) {
+                    return;
+                }
+                const classNode = node.parent;
+                context.report({
+                    node: classNode.id ?? node,
+                    messageId: 'tooManyFields',
+                    data: {
+                        name: classNode.id?.name ?? '(anonymous)',
+                        count: fields.length,
+                        max,
+                        names: fields.join(', '),
+                    },
+                });
+            },
+        };
+    },
+});

package/dist/rules/max-returns.d.ts

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

package/dist/rules/max-returns.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_MAX = 3;
+/**
+ * The name to report a function by. Declarations carry their own; the rest
+ * borrow it from whatever binds them, so a method and an arrow assigned to a
+ * const are named rather than reported as anonymous.
+ */
+const nameOf = (node) => {
+    if (node.id !== null) {
+        return node.id.name;
+    }
+    const parent = node.parent;
+    if ((parent.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
+        parent.type === utils_1.AST_NODE_TYPES.PropertyDefinition ||
+        parent.type === utils_1.AST_NODE_TYPES.Property) &&
+        !parent.computed &&
+        parent.key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return parent.key.name;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return parent.id.name;
+    }
+    return '(anonymous)';
+};
+exports.default = (0, createRule_1.createRule)({
+    name: 'max-returns',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce a maximum number of return statements per function.',
+        },
+        messages: {
+            tooManyReturns: "Function '{{name}}' returns from {{count}} places (max {{max}}). Consider collapsing the branches or extracting them into named functions.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: { type: 'integer', minimum: 1 },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ max: DEFAULT_MAX }],
+    create(context, [{ max }]) {
+        const sourceCode = context.sourceCode;
+        const scopes = [];
+        const enter = (node) => {
+            scopes.push({ node, count: 0 });
+        };
+        const leave = () => {
+            const scope = scopes.pop();
+            if (scope === undefined || scope.count <= max) {
+                return;
+            }
+            const { node, count } = scope;
+            const signature = node.id ?? sourceCode.getFirstToken(node);
+            context.report({
+                loc: (signature ?? node).loc,
+                messageId: 'tooManyReturns',
+                data: {
+                    name: nameOf(node),
+                    count,
+                    max,
+                },
+            });
+        };
+        return {
+            ArrowFunctionExpression: enter,
+            'ArrowFunctionExpression:exit': leave,
+            FunctionDeclaration: enter,
+            'FunctionDeclaration:exit': leave,
+            FunctionExpression: enter,
+            'FunctionExpression:exit': leave,
+            ReturnStatement() {
+                const scope = scopes[scopes.length - 1];
+                if (scope !== undefined) {
+                    scope.count += 1;
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-comments-in-function-body.d.ts

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

package/dist/rules/no-comments-in-function-body.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+/**
+ * Comments the toolchain reads rather than humans. Suppressing another rule or
+ * a type error inside a body is routine and says nothing about the code's shape,
+ * so these never count — the counterpart of qulice's `@checkstyle` exemption.
+ */
+const DIRECTIVES = [
+    '@ts-',
+    '@vite-ignore',
+    'c8 ignore',
+    'eslint',
+    'istanbul ignore',
+    'prettier-ignore',
+    'v8 ignore',
+    'webpackChunkName',
+];
+const directs = (comment, allow) => {
+    const text = comment.value.trim();
+    return [...DIRECTIVES, ...allow].some((prefix) => text.startsWith(prefix));
+};
+const encloses = (block, comment) => block.range[0] < comment.range[0] && comment.range[1] < block.range[1];
+const span = (block) => block.range[1] - block.range[0];
+/**
+ * The tightest block wrapping the comment, which is what decides whether it is
+ * merely annotating an empty one. An empty `catch` inside a busy function still
+ * earns its explanation, so the lookup cannot stop at the function body.
+ */
+const innermost = (blocks, comment) => blocks
+    .filter((block) => encloses(block, comment))
+    .reduce((tightest, block) => tightest === undefined || span(block) < span(tightest)
+    ? block
+    : tightest, undefined);
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-comments-in-function-body',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow comments inside function bodies, where they stand in for a name the code should carry itself.',
+        },
+        messages: {
+            commentInBody: 'A comment inside a function body signals code that needs a better name. Move it to a docblock above the function, or extract what it explains into a named function.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allow: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ allow: [] }],
+    create(context, [{ allow }]) {
+        const sourceCode = context.sourceCode;
+        const bodies = [];
+        const blocks = [];
+        const collect = (node) => {
+            if (node.body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+                bodies.push(node.body);
+            }
+        };
+        return {
+            BlockStatement(node) {
+                blocks.push(node);
+            },
+            ArrowFunctionExpression: collect,
+            FunctionDeclaration: collect,
+            FunctionExpression: collect,
+            'Program:exit'() {
+                for (const comment of sourceCode.getAllComments()) {
+                    const inside = bodies.some((body) => encloses(body, comment));
+                    const block = innermost(blocks, comment);
+                    const explains = block === undefined || block.body.length === 0;
+                    if (inside && !explains && !directs(comment, allow)) {
+                        context.report({ loc: comment.loc, messageId: 'commentInBody' });
+                    }
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-else-after-throw.d.ts

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

package/dist/rules/no-else-after-throw.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+/**
+ * Whether the branch leaves through a `throw` no matter what. A bare `throw`
+ * qualifies, as does a block whose last statement is one. The check does not
+ * recurse: a block ending in a nested `if` may or may not throw, and `else`
+ * still carries information there.
+ */
+const alwaysThrows = (branch) => {
+    if (branch.type === utils_1.AST_NODE_TYPES.ThrowStatement) {
+        return true;
+    }
+    if (branch.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+        return false;
+    }
+    return branch.body.at(-1)?.type === utils_1.AST_NODE_TYPES.ThrowStatement;
+};
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-else-after-throw',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow an else branch when the then branch always throws.',
+        },
+        messages: {
+            elseAfterThrow: "The 'then' branch always throws, so 'else' adds nothing but nesting. Drop it and let the alternative sit at the outer level.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const sourceCode = context.sourceCode;
+        return {
+            IfStatement(node) {
+                if (node.alternate === null || !alwaysThrows(node.consequent)) {
+                    return;
+                }
+                const keyword = sourceCode.getTokenBefore(node.alternate);
+                context.report({
+                    node: keyword ?? node.alternate,
+                    messageId: 'elseAfterThrow',
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-interpolated-log-message.d.ts

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

package/dist/rules/no-interpolated-log-message.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const OBJECTS = ['log', 'logger'];
+const METHODS = [
+    'debug',
+    'error',
+    'fatal',
+    'info',
+    'log',
+    'trace',
+    'verbose',
+    'warn',
+];
+/**
+ * The name a call hangs off, as written. `logger.info` yields `logger`, and
+ * `this.logger.info` yields `logger` too, so a field and a local read alike.
+ */
+const receiver = (node) => {
+    if (node.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.name;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !node.computed &&
+        node.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.property.name;
+    }
+    return undefined;
+};
+/**
+ * The message is the first argument that is not an object literal, which lands
+ * on the message under either convention: `info(msg, data)` as in Nest and
+ * winston, and `info(data, msg)` as in pino.
+ */
+const message = (args) => args.find((arg) => arg.type !== utils_1.AST_NODE_TYPES.ObjectExpression);
+const computed = (node) => (node.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
+    node.expressions.length > 0) ||
+    (node.type === utils_1.AST_NODE_TYPES.BinaryExpression && node.operator === '+');
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-interpolated-log-message',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require log messages to be constant, with the varying parts passed as structured data.',
+        },
+        messages: {
+            interpolatedMessage: 'A computed log message cannot be grouped or searched. Keep the message constant and pass the varying parts as structured data.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    objects: { type: 'array', items: { type: 'string' } },
+                    methods: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ objects: [], methods: [] }],
+    create(context, [{ objects, methods }]) {
+        const logging = new Set([...OBJECTS, ...objects]);
+        const levels = new Set([...METHODS, ...methods]);
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                    callee.computed ||
+                    callee.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    !levels.has(callee.property.name)) {
+                    return;
+                }
+                const name = receiver(callee.object);
+                if (name === undefined || !logging.has(name)) {
+                    return;
+                }
+                const argument = message(node.arguments);
+                if (argument !== undefined && computed(argument)) {
+                    context.report({
+                        node: argument,
+                        messageId: 'interpolatedMessage',
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/utils/createRule.d.ts

@@ -1,7 +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.
+ * every rule links back to its section in the README. The anchor matches the
+ * `#### \`<name>\`` heading GitHub generates for each rule under "Rule details".
  */
 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

@@ -4,6 +4,7 @@ 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.
+ * every rule links back to its section in the README. The anchor matches the
+ * `#### \`<name>\`` heading GitHub generates for each rule under "Rule details".
  */
-exports.createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/tianjos/eslint-plugin-elegant/blob/main/docs/rules/${name}.md`);
+exports.createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/tianjos/eslint-plugin-elegant/blob/main/README.md#${name}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tianjos/eslint-plugin-elegant",
-  "version": "0.3.1",
-  "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.",
+  "version": "0.4.0",
+  "description": "Opinionated ESLint rules for elegant, behavior-rich TypeScript: honest types, encapsulated state, small uncoupled classes, guard-clause flow, and structured logging. Built for NestJS and DDD codebases.",
   "keywords": [
     "eslint",
     "eslint-plugin",