@tianjos/eslint-plugin-elegant 0.7.2 → 0.9.0

package/README.md

@@ -63,14 +63,25 @@ export default [
 ];
 ```
 
+Adopting this on a codebase that already exists? Spread
+`elegant.configs.starter` instead — same rules, with the four heaviest demoted
+so the first run gives you a list you can work through. See
+[Adopting on an existing codebase](#adopting-on-an-existing-codebase).
+
 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 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).
+The plugin exports two configs, both carrying every rule below 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):
+
+- **`recommended`** — the severities in the table below. What the plugin
+  argues for.
+- **`starter`** — the same rules with the four heaviest demoted, for adopting
+  on a codebase that already exists. See
+  [Adopting on an existing codebase](#adopting-on-an-existing-codebase).
 
 | Rule                                   | Source | What it catches                                                                 | `recommended` |
 | -------------------------------------- | ------ | ------------------------------------------------------------------------------- | ------------- |
@@ -245,6 +256,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
@@ -730,19 +779,31 @@ 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:
+rather than inherit. That is what `starter` is: every rule `recommended`
+carries, with those four demoted, leaving the 1.75 per file below them — a
+list somebody can actually work through.
 
 ```js
 rules: {
-  ...elegant.configs.recommended.rules,
+  ...elegant.configs.starter.rules,
+}
+```
+
+| | `recommended` | `starter` |
+| --- | --- | --- |
+| `no-comments-in-function-body` | `error` | `off` |
+| `no-interpolated-log-message` | `error` | `warn` |
+| `no-null` | `error` | `warn` |
+| `no-type-assertion` | `error` | `warn` |
+| everything else | unchanged | unchanged |
+
+Promote them back one at a time as you clear them, and switch to
+`recommended` once nothing is left:
 
-  // 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',
+```js
+rules: {
+  ...elegant.configs.starter.rules,
+  'elegant/no-null': 'error',   // cleared, so hold the line
 }
 ```
 
@@ -775,7 +836,9 @@ block scoped to your spec globs:
 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 }`.
+exposes `{ meta, rules, configs }`, where `configs` holds `recommended` and
+`starter`. All three load paths are exercised against the built output by
+`tests/dist.test.ts`.
 
 ## Prior art
 

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/index.js

@@ -88,5 +88,32 @@ plugin.configs.recommended = {
         'no-else-return': ['error', { allowElseIf: false }],
     },
 };
+/**
+ * The four rules that carry most of the friction on code that already exists.
+ * Each encodes a defensible position whose boundary this plugin cannot see —
+ * a comment that wants to be a function, a logging convention already chosen,
+ * `null` as the wire format of a column, an assertion widening a type — so on
+ * a mature codebase they report by the thousand. `recommended` keeps them at
+ * `error` on purpose; `starter` is the door in.
+ */
+const NOISIEST = {
+    'elegant/no-comments-in-function-body': 'off',
+    'elegant/no-interpolated-log-message': 'warn',
+    'elegant/no-null': 'warn',
+    'elegant/no-type-assertion': 'warn',
+};
+/**
+ * Every rule `recommended` carries, with the four heaviest demoted so the
+ * first run on an existing codebase produces a list somebody can work through.
+ * Promote them back one at a time; see "Adopting on an existing codebase".
+ */
+plugin.configs.starter = {
+    name: 'elegant/starter',
+    plugins: { elegant: plugin },
+    rules: {
+        ...plugin.configs.recommended.rules,
+        ...NOISIEST,
+    },
+};
 plugin.default = plugin;
 module.exports = plugin;

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.9.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",
@@ -43,7 +43,7 @@
     "build": "tsc -p tsconfig.json",
     "lint": "npm run build && eslint .",
     "typecheck": "tsc -p tsconfig.test.json",
-    "test": "jest",
+    "test": "npm run build && jest",
     "release": "standard-version --release-as minor",
     "release:patch": "standard-version --release-as patch",
     "prepublishOnly": "npm run build && npm test"