@tianjos/eslint-plugin-elegant 0.7.2 → 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

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.2",
+  "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",