@tianjos/eslint-plugin-elegant 0.5.0 → 0.6.0

package/README.md

@@ -84,7 +84,7 @@ The `recommended` config enables every custom rule plus two native ones,
 | `elegant/no-logic-in-constructor`      | custom | Any constructor code beyond `this.field = value` stores and a `super(...)` call  | `error`       |
 | `elegant/no-getters-setters`           | custom | `get`/`set` accessors (and `getX`/`setX` methods with `{ methods: true }`)        | `error`       |
 | `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-static-members`            | custom | Static methods, properties, accessors, and blocks (secondary constructors and Nest module factories excepted) | `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`       |
@@ -212,8 +212,46 @@ the codebase.
 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.
+constants.
+
+Two kinds of static are allowed by default, because neither is behaviour that
+anyone would want to substitute.
+
+**A secondary constructor** — a static whose declared return type is the class
+itself. TypeScript cannot overload a constructor, so `static of(...): DueDate`
+inside `DueDate` is the only way to write one, and calling it is
+indistinguishable from calling `new`. That is what separates a named
+constructor from a procedure that moved into a class:
+
+```ts
+class DueDate {
+  static of(props: DueDateProps): DueDate {}     // allowed
+  static parse(raw: unknown): DueDate {}         // allowed
+}
+
+class DocumentFormatter {
+  static formatCNPJ(document: string): string {} // reported — a module function
+}
+```
+
+`this`, `Promise<Self>` and `Self | undefined` all count: a polymorphic, an
+asynchronous and a failing constructor are still constructors. `Self | null`
+does not, because `no-null-return` already owns that shape. The return type has
+to be **written down** — the rule carries no type information, so an
+unannotated `static create() { … }` stays reported. On a factory the annotation
+is one word, and it is what makes the intent legible. Off via
+`{ allowSelfReturning: false }`.
+
+**A Nest module factory** — a static returning `DynamicModule` from a class
+decorated with `@Module`. `forRoot`, `forRootAsync`, `register` and
+`registerAsync` are mandated by the framework, not chosen by the design. Both
+halves are required, so naming `DynamicModule` in a return type is not a way
+out of the rule, and a module class gets no blanket exemption for its other
+statics. Off via `{ allowModuleFactories: false }`.
+
+Everything else still reports: static accessors (reading one is reaching for
+static state, whatever it returns), `private static` helpers, and static
+classes used as a namespace for functions.
 
 #### `no-null`
 

package/dist/index.d.ts

@@ -42,6 +42,8 @@ declare const rules: {
     };
     'no-static-members': TSESLint.RuleModule<"staticMember", [{
         allowReadonly: boolean;
+        allowSelfReturning: boolean;
+        allowModuleFactories: boolean;
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };

package/dist/rules/no-static-members.d.ts

@@ -1,6 +1,9 @@
-type Options = [{
+type Allowances = {
     allowReadonly: boolean;
-}];
+    allowSelfReturning: boolean;
+    allowModuleFactories: boolean;
+};
+type Options = [Allowances];
 declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"staticMember", Options, unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
     name: string;
 };

package/dist/rules/no-static-members.js

@@ -1,6 +1,72 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+/**
+ * Whether the annotation denotes the class itself. TypeScript has no secondary
+ * constructors, so `static of(...): DueDate` inside `DueDate` is the only way
+ * to write one — and calling it is indistinguishable from calling `new`, which
+ * is what separates a named constructor from a procedure that moved into a
+ * class.
+ *
+ * `this`, `Promise<Self>` and `Self | undefined` all count: a polymorphic, an
+ * asynchronous and a failing constructor are still constructors. `Self | null`
+ * deliberately does not, because `no-null-return` already owns that shape.
+ */
+const isNamed = (node, name) => node.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+    node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+    node.typeName.name === name;
+/** What a `Promise<T>` resolves to, or the node itself. */
+const awaited = (node) => isNamed(node, 'Promise') && node.type === utils_1.AST_NODE_TYPES.TSTypeReference
+    ? (node.typeArguments?.params[0] ?? node)
+    : node;
+const isSelf = (node, className) => {
+    const resolved = awaited(node);
+    if (resolved.type === utils_1.AST_NODE_TYPES.TSThisType) {
+        return true;
+    }
+    if (resolved.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+        return (resolved.types.some((member) => isSelf(member, className)) &&
+            resolved.types.every((member) => isSelf(member, className) ||
+                member.type === utils_1.AST_NODE_TYPES.TSUndefinedKeyword));
+    }
+    return isNamed(resolved, className);
+};
+/**
+ * A Nest module factory: `DynamicModule` returned from a class Nest recognises
+ * as a module. Both halves are required, so `DynamicModule` cannot become a
+ * general escape from the rule by being named in a return type.
+ */
+const isModuleFactory = (method) => {
+    const annotation = method.value.returnType?.typeAnnotation;
+    if (annotation === undefined || !isNamed(awaited(annotation), 'DynamicModule')) {
+        return false;
+    }
+    return method.parent.parent.decorators.some((decorator) => decorator.expression.type === utils_1.AST_NODE_TYPES.CallExpression
+        ? isModuleIdentifier(decorator.expression.callee)
+        : isModuleIdentifier(decorator.expression));
+};
+const isModuleIdentifier = (node) => node.type === utils_1.AST_NODE_TYPES.Identifier && node.name === 'Module';
+/**
+ * A secondary constructor's return, read from the annotation alone. The rule
+ * carries no type information, so an unannotated static stays reported: on a
+ * factory the annotation is one word, and it is what makes the intent legible.
+ */
+const returnsSelf = (method, className) => {
+    const annotation = method.value.returnType?.typeAnnotation;
+    return (className !== undefined &&
+        annotation !== undefined &&
+        isSelf(annotation, className));
+};
+/**
+ * A static the rule lets through: a secondary constructor, or a module factory
+ * the framework demands. An accessor is neither, whatever it returns — reading
+ * one is reaching for static state.
+ */
+const isPermitted = (node, allow) => node.kind === 'method' &&
+    ((allow.allowSelfReturning &&
+        returnsSelf(node, node.parent.parent.id?.name)) ||
+        (allow.allowModuleFactories && isModuleFactory(node)));
 exports.default = (0, createRule_1.createRule)({
     name: 'no-static-members',
     meta: {
@@ -14,24 +80,34 @@ exports.default = (0, createRule_1.createRule)({
         schema: [
             {
                 type: 'object',
-                properties: { allowReadonly: { type: 'boolean' } },
+                properties: {
+                    allowReadonly: { type: 'boolean' },
+                    allowSelfReturning: { type: 'boolean' },
+                    allowModuleFactories: { type: 'boolean' },
+                },
                 additionalProperties: false,
             },
         ],
     },
-    defaultOptions: [{ allowReadonly: false }],
-    create(context, [{ allowReadonly }]) {
+    defaultOptions: [
+        {
+            allowReadonly: false,
+            allowSelfReturning: true,
+            allowModuleFactories: true,
+        },
+    ],
+    create(context, [allow]) {
         const reportKey = (key) => {
             context.report({ node: key, messageId: 'staticMember' });
         };
         return {
             MethodDefinition(node) {
-                if (node.static) {
+                if (node.static && !isPermitted(node, allow)) {
                     reportKey(node.key);
                 }
             },
             PropertyDefinition(node) {
-                if (node.static && !(allowReadonly && node.readonly)) {
+                if (node.static && !(allow.allowReadonly && node.readonly)) {
                     reportKey(node.key);
                 }
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianjos/eslint-plugin-elegant",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -44,7 +44,8 @@
     "lint": "npm run build && eslint .",
     "typecheck": "tsc -p tsconfig.test.json",
     "test": "jest",
-    "release": "standard-version",
+    "release": "standard-version --release-as minor",
+    "release:patch": "standard-version --release-as patch",
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {