@tianjos/eslint-plugin-elegant 0.7.1 → 0.8.0

package/README.md

@@ -245,6 +245,44 @@ around repositories and framework hooks, so it stays off in `recommended`.
 the object. Pairs with `no-type-assertion` to keep type-based branching out of
 the codebase.
 
+Two uses are allowed by default, because in both of them TypeScript leaves no
+polymorphic alternative to reach for.
+
+**A self-guard** — `other instanceof Money` inside `class Money`. Value
+equality has to guard its own type before comparing fields, and there is no
+polymorphic way to write that: the method is already on the object, so the
+rule's own advice has nowhere left to go. Guarding against a *different* type
+(`other instanceof Currency` inside `Money`) is discrimination and is still
+reported. Off via `{ allowSelfGuard: false }`.
+
+**A caught value** — a name a `catch` clause introduced. TypeScript types it
+as `unknown`, so `instanceof` is the only narrowing the language offers; no
+method on the value can stand in, because at that point the value has no known
+methods. Resolved through the scope chain, so the narrowing still counts one
+closure deeper. Off via `{ allowCaughtValues: false }`.
+
+```ts
+// allowed
+class Money {
+  equals(other?: unknown): boolean {
+    return other instanceof Money && this.amount === other.amount;
+  }
+}
+try { charge(); } catch (error) {
+  if (error instanceof HttpException) { log(error.getStatus()); }
+}
+
+// still reported
+if (shape instanceof Circle) { draw(); }
+function handle(error: HttpException) { return error instanceof HttpException; }
+```
+
+An error that arrives as a plain parameter rather than through `catch` — Nest's
+`ExceptionFilter.catch(exception, host)`, an RxJS `catchError` callback — is
+**not** covered, because a parameter's type is whatever the signature says and
+the rule reads no type information. Narrow it once at the boundary, or disable
+the rule for those files.
+
 #### `no-static-members`
 
 Static state and behavior cannot be injected, substituted, or mocked. Prefer
@@ -683,6 +721,74 @@ rules: {
 }
 ```
 
+### Adopting on an existing codebase
+
+The `recommended` config is written for the code you wish you had. Turning it
+on over code that already exists is a different exercise, and worth planning
+with numbers rather than discovering at the first `eslint .`.
+
+Measured over **1,261 production TypeScript files** across three NestJS
+services — a DTO-heavy, string-logging, TypeORM-backed shape this preset was
+built for:
+
+| Rule | Severity | Reports | Per file | In test files |
+| --- | --- | ---: | ---: | ---: |
+| `no-comments-in-function-body` | `error` | 5,559 | 4.41 | 2,589 |
+| `no-interpolated-log-message` | `error` | 1,941 | 1.54 | 0 |
+| `no-null` | `error` | 1,367 | 1.08 | 896 |
+| `no-type-assertion` | `error` | 524 | 0.42 | 935 |
+| `max-method-lines` | `warn` | 467 | 0.37 | 1 |
+| `max-params` | `warn` | 195 | 0.15 | 6 |
+| `no-null-return` | `error` | 194 | 0.15 | 2 |
+| `no-instanceof` | `error` | 179 | 0.14 | 0 |
+| `no-generic-error` | `error` | 163 | 0.13 | 17 |
+| `max-returns` | `warn` | 125 | 0.10 | 0 |
+| `no-public-mutable-props` | `error` | 116 | 0.09 | 0 |
+| `no-property-alias` | `error` | 111 | 0.09 | 1 |
+| `no-logic-in-constructor` | `error` | 98 | 0.08 | 0 |
+| `no-static-members` | `error` | 96 | 0.08 | 0 |
+| `no-anonymous-param-type` | `error` | 91 | 0.07 | 27 |
+| `no-self-mutation` | `error` | 66 | 0.05 | 0 |
+| `max-class-dependencies` | `warn` | 64 | 0.05 | 0 |
+| `max-class-fields` | `warn` | 57 | 0.05 | 0 |
+| `no-property-destructuring` | `error` | 53 | 0.04 | 0 |
+| `no-boolean-param` | `error` | 47 | 0.04 | 1 |
+| `max-class-methods` | `warn` | 40 | 0.03 | 0 |
+| `no-getters-setters` | `error` | 29 | 0.02 | 0 |
+| `no-else-return` | `error` | 13 | 0.01 | 0 |
+| `no-else-after-throw` | `error` | 8 | 0.01 | 0 |
+| **Total** | | **11,603** | **9.20** | |
+
+Four rules account for 81% of it, and they are the four whose principle has a
+boundary this plugin cannot see. `no-comments-in-function-body` asks you to
+rewrite a function, not edit a line. `no-interpolated-log-message` fires on
+whatever logging convention the project already chose, so on a codebase that
+logs with template strings it fires everywhere. `no-null` cannot tell a domain
+value from the wire format of a database column. `no-type-assertion` counts
+`x as unknown as T` twice, once per assertion, which is arguably correct.
+
+None of that makes them wrong — it makes them rules you adopt on purpose
+rather than inherit. **Enable the preset, then take the top of that table back
+to `warn` or `off` and work down it.** The rules below `no-type-assertion` sum
+to 1.75 per file, which is a starting point you can actually clear:
+
+```js
+rules: {
+  ...elegant.configs.recommended.rules,
+
+  // The four that need a plan of their own. Re-enable one at a time.
+  'elegant/no-comments-in-function-body': 'off',
+  'elegant/no-interpolated-log-message': 'warn',
+  'elegant/no-null': 'warn',
+  'elegant/no-type-assertion': 'warn',
+}
+```
+
+Numbers from one corpus are indicative, not universal. Run
+`npx eslint . --format json` on your own and sort by rule before deciding
+anything — the shape of your code decides which of these rules is a signal and
+which is a migration.
+
 ### Relaxing rules in test files
 
 Tests routinely use flag arguments and larger fixtures. Add a second config

package/dist/index.d.ts

@@ -40,7 +40,10 @@ declare const rules: {
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };
-    'no-instanceof': TSESLint.RuleModule<"noInstanceof", [], unknown, TSESLint.RuleListener> & {
+    'no-instanceof': TSESLint.RuleModule<"noInstanceof", [{
+        allowSelfGuard: boolean;
+        allowCaughtValues: boolean;
+    }], unknown, TSESLint.RuleListener> & {
         name: string;
     };
     'no-static-members': TSESLint.RuleModule<"staticMember", [{

package/dist/rules/no-instanceof.d.ts

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

package/dist/rules/no-instanceof.js

@@ -1,6 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const ancestors_1 = require("../utils/ancestors");
 const createRule_1 = require("../utils/createRule");
+const locals_1 = require("../utils/locals");
+/** The name of the class a node sits inside, if it sits inside a named one. */
+const enclosingClass = (node) => {
+    const found = (0, ancestors_1.closestAncestor)(node, (candidate) => candidate.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
+        candidate.type === utils_1.AST_NODE_TYPES.ClassExpression);
+    return found?.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
+        found?.type === utils_1.AST_NODE_TYPES.ClassExpression
+        ? found.id?.name
+        : undefined;
+};
+/**
+ * `other instanceof Money` inside `class Money`. Value equality has to guard
+ * its own type before comparing fields, and a structurally typed language
+ * offers no polymorphic way to do it: the method is already on the object, so
+ * the rule's own advice has nowhere left to go.
+ */
+const isSelfGuard = (node) => node.right.type === utils_1.AST_NODE_TYPES.Identifier &&
+    node.right.name === enclosingClass(node);
 exports.default = (0, createRule_1.createRule)({
     name: 'no-instanceof',
     meta: {
@@ -11,12 +31,29 @@ exports.default = (0, createRule_1.createRule)({
         messages: {
             noInstanceof: 'Avoid `instanceof`. Replace type discrimination with a polymorphic method on the object.',
         },
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allowSelfGuard: { type: 'boolean' },
+                    allowCaughtValues: { type: 'boolean' },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
-    defaultOptions: [],
-    create(context) {
+    defaultOptions: [{ allowSelfGuard: true, allowCaughtValues: true }],
+    create(context, [{ allowSelfGuard, allowCaughtValues }]) {
         return {
             'BinaryExpression[operator="instanceof"]'(node) {
+                if (allowSelfGuard && isSelfGuard(node)) {
+                    return;
+                }
+                if (allowCaughtValues &&
+                    node.left.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    (0, locals_1.isCaughtBinding)(context.sourceCode.getScope(node), node.left.name)) {
+                    return;
+                }
                 context.report({ node, messageId: 'noInstanceof' });
             },
         };

package/dist/rules/no-self-mutation.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@typescript-eslint/utils");
+const ancestors_1 = require("../utils/ancestors");
 const createRule_1 = require("../utils/createRule");
 /**
  * Nest calls these after the container has built the instance, so they finish
@@ -24,36 +25,34 @@ const fieldOf = (target) => target.type === utils_1.AST_NODE_TYPES.MemberExpress
     target.property.type === utils_1.AST_NODE_TYPES.Identifier
     ? target.property.name
     : undefined;
+/**
+ * Whether the write sits inside a class body at all. `this` outside one is
+ * `module.exports`, `undefined`, or an object literal's own receiver — none of
+ * which is an object with holders to surprise, so the rule has nothing to say
+ * about them.
+ */
+const isInsideClass = (node) => (0, ancestors_1.closestAncestor)(node, (candidate) => candidate.type === utils_1.AST_NODE_TYPES.ClassBody ||
+    candidate.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
+    candidate.type === utils_1.AST_NODE_TYPES.ClassExpression) !== undefined;
 /**
  * Whether the write happens while the object is still being built. Only the
  * constructor's own body counts: a callback the constructor schedules runs
  * after construction has returned, so it mutates a finished object.
  */
 const isDuringConstruction = (node) => {
-    let current = node;
-    while (current !== undefined) {
-        if (current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
-            current.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
-            current.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
-            return (current.parent?.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
-                current.parent.kind === 'constructor');
-        }
-        current = current.parent;
-    }
-    return false;
+    const fn = (0, ancestors_1.closestAncestor)(node, (candidate) => candidate.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        candidate.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        candidate.type === utils_1.AST_NODE_TYPES.FunctionExpression);
+    return (fn?.parent?.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+        fn.parent.kind === 'constructor');
 };
 /** The method a write sits in, if it sits in one directly. */
 const enclosingMethod = (node) => {
-    let current = node;
-    while (current !== undefined) {
-        if (current.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
-            return current.key.type === utils_1.AST_NODE_TYPES.Identifier
-                ? current.key.name
-                : undefined;
-        }
-        current = current.parent;
-    }
-    return undefined;
+    const method = (0, ancestors_1.closestAncestor)(node, (candidate) => candidate.type === utils_1.AST_NODE_TYPES.MethodDefinition);
+    return method?.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+        method.key.type === utils_1.AST_NODE_TYPES.Identifier
+        ? method.key.name
+        : undefined;
 };
 exports.default = (0, createRule_1.createRule)({
     name: 'no-self-mutation',
@@ -79,7 +78,9 @@ exports.default = (0, createRule_1.createRule)({
     create(context, [{ allowedMethods }]) {
         const check = (node, target) => {
             const name = fieldOf(target);
-            if (name === undefined || isDuringConstruction(node)) {
+            if (name === undefined ||
+                !isInsideClass(node) ||
+                isDuringConstruction(node)) {
                 return;
             }
             const method = enclosingMethod(node);

package/dist/utils/ancestors.d.ts

@@ -0,0 +1,10 @@
+import { TSESTree } from '@typescript-eslint/utils';
+/**
+ * The innermost ancestor a predicate accepts, or `undefined` if the walk
+ * reaches the top without one.
+ *
+ * `Program.parent` is `null` rather than `undefined`, so a walk that only
+ * guards against `undefined` runs off the top of the tree and throws — which
+ * takes the whole lint run for that file down with it.
+ */
+export declare const closestAncestor: (node: TSESTree.Node, matches: (candidate: TSESTree.Node) => boolean) => TSESTree.Node | undefined;

package/dist/utils/ancestors.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closestAncestor = void 0;
+/**
+ * The innermost ancestor a predicate accepts, or `undefined` if the walk
+ * reaches the top without one.
+ *
+ * `Program.parent` is `null` rather than `undefined`, so a walk that only
+ * guards against `undefined` runs off the top of the tree and throws — which
+ * takes the whole lint run for that file down with it.
+ */
+const closestAncestor = (node, matches) => {
+    let current = node.parent;
+    while (current !== null && current !== undefined) {
+        if (matches(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return undefined;
+};
+exports.closestAncestor = closestAncestor;

package/dist/utils/locals.d.ts

@@ -11,3 +11,10 @@ export declare const isReassigned: (variable: TSESLint.Scope.Variable) => boolea
  * so such a declaration is load-bearing: inlining it stops compiling.
  */
 export declare const escapesIntoFunction: (variable: TSESLint.Scope.Variable) => boolean;
+/**
+ * Whether a name resolves to a binding a `catch` clause introduced.
+ * TypeScript types a caught value as `unknown`, so `instanceof` is the only
+ * narrowing the language offers there — no method on the value can stand in
+ * for it, because at that point the value has no known methods.
+ */
+export declare const isCaughtBinding: (scope: TSESLint.Scope.Scope, name: string) => boolean;

package/dist/utils/locals.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.escapesIntoFunction = exports.isReassigned = void 0;
+exports.isCaughtBinding = exports.escapesIntoFunction = exports.isReassigned = void 0;
 /**
  * Whether anything writes to the variable after its declaration. Such a local
  * holds mutable state that no member access stands in for, so it is not a copy
@@ -24,3 +24,21 @@ const escapesIntoFunction = (variable) => variable.references.some((reference) =
     return false;
 });
 exports.escapesIntoFunction = escapesIntoFunction;
+/**
+ * Whether a name resolves to a binding a `catch` clause introduced.
+ * TypeScript types a caught value as `unknown`, so `instanceof` is the only
+ * narrowing the language offers there — no method on the value can stand in
+ * for it, because at that point the value has no known methods.
+ */
+const isCaughtBinding = (scope, name) => {
+    let current = scope;
+    while (current !== null) {
+        const found = current.variables.find((variable) => variable.name === name);
+        if (found !== undefined) {
+            return found.defs.some((def) => def.type === 'CatchClause');
+        }
+        current = current.upper;
+    }
+    return false;
+};
+exports.isCaughtBinding = isCaughtBinding;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianjos/eslint-plugin-elegant",
-  "version": "0.7.1",
+  "version": "0.8.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",