@tianjos/eslint-plugin-elegant 0.6.0 → 0.7.0

package/README.md

@@ -93,6 +93,9 @@ The `recommended` config enables every custom rule plus two native ones,
 | `elegant/no-property-alias`            | custom | Locals that only rename a property of an object already in hand                 | `error`       |
 | `elegant/no-property-destructuring`    | custom | Destructuring an object already in hand into locals                             | `error`       |
 | `elegant/no-anonymous-param-type`      | custom | Parameters typed as an anonymous shape of `minMembers` or more properties        | `error` (minMembers 2) |
+| `elegant/no-self-mutation`             | custom | Writing to your own fields outside the constructor                              | `error`       |
+| `elegant/no-generic-error`             | custom | `throw new Error(...)` and the other built-in error types                       | `error`       |
+| `elegant/max-method-lines`             | custom | Named functions and methods longer than `max` lines                             | `warn` (max 50) |
 | `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`       |
 
@@ -183,7 +186,18 @@ 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.
+invariants. A declared `private`/`protected` field is allowed, and so is any
+`readonly` member.
+
+Constructor parameter properties are covered at **every** visibility by
+default, which declared fields are not: a `private repo: Repository<Proposal>`
+that nobody marked `readonly` can still be swapped from inside, and unlike a
+declared field it is a collaborator the container handed you. Set
+`{ parameterProperties: 'public' }` to keep the rule to what its name says.
+
+This rule asks whether a field is *declared* changeable. Its behavioural
+counterpart is `no-self-mutation`, which asks whether anything actually
+changes it.
 
 #### `no-logic-in-constructor`
 
@@ -554,6 +568,80 @@ Unlike its neighbours, this rule does not have a mechanical fix: it asks you to
 introduce a named type and decide where it lives. That is a design change, so
 expect adoption to cost more than a find-and-replace.
 
+#### `no-self-mutation`
+
+`no-public-mutable-props` asks whether a field is *declared* changeable. This
+asks whether anything actually changes it. A write to `this.something` after
+the constructor has returned means the object is not a value anyone can hold
+with confidence: whoever received it a moment ago is now holding something
+else.
+
+```ts
+// reported — each one is a lifecycle, not a value
+this.accessToken = access_token;
+this.isPolling = false;
+this.filterOptionsCache = options;
+this.snsClient = new SNSClient({});
+
+// passes — this is where an object is built
+constructor(private readonly token: string) {
+  this.expiresAt = expiry(token);
+}
+```
+
+Compound assignment (`this.count += 1`) and increment (`this.count++`) are
+writes too. A computed write (`this[key] = value`) names no field and is left
+alone. Writing to *another* object (`box.value = v`) is that object's business.
+
+A callback the constructor schedules is **not** construction — it runs after
+the constructor returned, so `setTimeout(() => { this.token = load(); })`
+inside a constructor is reported.
+
+Nest calls `onModuleInit`, `onApplicationBootstrap`, `onModuleDestroy`,
+`beforeApplicationShutdown` and `onApplicationShutdown` after the container has
+built the instance, finishing a construction the constructor could not — a
+timer needs a running event loop. Those five are allowed by default, and the
+list is the `{ allowedMethods: string[] }` option; pass `[]` to hold them to
+the same standard, or add your own.
+
+#### `no-generic-error`
+
+`throw new Error('RETRY_BATCH_QUEUE_URL not configured')` describes the failure
+only in a string the thrower is free to reword. A caller that wants to handle
+that case specifically has nothing to catch but `Error`, which every other
+failure also is, so it ends up matching on the message.
+
+```ts
+// reported
+throw new Error('origin codes are required');
+throw new TypeError('not a number');
+
+// passes
+throw new MissingOriginCodes();
+throw new ProposalNotFound(id);
+throw error;                     // rethrow keeps whatever it was
+throw invalidRow(raw);           // a factory decides which exception to build
+```
+
+Covers the eight built-in error types (`Error`, `TypeError`, `RangeError`,
+`ReferenceError`, `SyntaxError`, `EvalError`, `URIError`, `AggregateError`).
+A subclass is a named exception and passes — that is the whole point. Only
+`throw` is examined: building an `Error` to hand to `Promise.reject` or a
+callback is a different question and belongs to a different rule.
+
+#### `max-method-lines`
+
+A port of Checkstyle's `MethodLength`, which qulice runs. Measured from the
+signature to the closing brace, so the declaration and the blank lines that
+separate the body's paragraphs count — they are part of what a reader has to
+hold.
+
+Named units are measured: methods, function declarations, and a function or
+arrow bound to a `const`. An inline callback is **not** measured on its own,
+because a long callback already makes its host long and the host is what gets
+reported. Configurable via `{ max: number }` (default `50`), and a `warn`
+rather than an `error`, like the other thresholds.
+
 ## Configuration
 
 ### Overriding thresholds

package/dist/index.d.ts

@@ -26,7 +26,9 @@ declare const rules: {
     'no-null-return': TSESLint.RuleModule<"noNullReturn", [], unknown, TSESLint.RuleListener> & {
         name: string;
     };
-    'no-public-mutable-props': TSESLint.RuleModule<"mutableProp", [], unknown, TSESLint.RuleListener> & {
+    'no-public-mutable-props': TSESLint.RuleModule<"mutableProp", [{
+        parameterProperties: "public" | "all";
+    }], unknown, TSESLint.RuleListener> & {
         name: string;
     };
     'no-logic-in-constructor': TSESLint.RuleModule<"statement" | "computation", [], unknown, TSESLint.RuleListener> & {
@@ -82,6 +84,19 @@ declare const rules: {
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };
+    'no-self-mutation': TSESLint.RuleModule<"mutatesSelf", [{
+        allowedMethods: string[];
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-generic-error': TSESLint.RuleModule<"genericError", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'max-method-lines': TSESLint.RuleModule<"tooManyLines", [{
+        max: number;
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
 };
 type Plugin = {
     meta: {

package/dist/index.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const no_anonymous_param_type_1 = __importDefault(require("./rules/no-anonymous-param-type"));
 const max_class_dependencies_1 = __importDefault(require("./rules/max-class-dependencies"));
+const max_method_lines_1 = __importDefault(require("./rules/max-method-lines"));
 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"));
@@ -15,7 +16,9 @@ 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_generic_error_1 = __importDefault(require("./rules/no-generic-error"));
 const no_null_return_1 = __importDefault(require("./rules/no-null-return"));
+const no_self_mutation_1 = __importDefault(require("./rules/no-self-mutation"));
 const no_property_alias_1 = __importDefault(require("./rules/no-property-alias"));
 const no_property_destructuring_1 = __importDefault(require("./rules/no-property-destructuring"));
 const no_public_mutable_props_1 = __importDefault(require("./rules/no-public-mutable-props"));
@@ -46,6 +49,9 @@ const rules = {
     'no-property-alias': no_property_alias_1.default,
     'no-property-destructuring': no_property_destructuring_1.default,
     'no-anonymous-param-type': no_anonymous_param_type_1.default,
+    'no-self-mutation': no_self_mutation_1.default,
+    'no-generic-error': no_generic_error_1.default,
+    'max-method-lines': max_method_lines_1.default,
 };
 const plugin = {
     meta: { name, version },
@@ -75,6 +81,9 @@ plugin.configs.recommended = {
         'elegant/no-property-alias': 'error',
         'elegant/no-property-destructuring': 'error',
         'elegant/no-anonymous-param-type': ['error', { minMembers: 2 }],
+        'elegant/no-self-mutation': 'error',
+        'elegant/no-generic-error': 'error',
+        'elegant/max-method-lines': ['warn', { max: 50 }],
         'max-params': ['warn', { max: 3 }],
         'no-else-return': ['error', { allowElseIf: false }],
     },

package/dist/rules/max-method-lines.d.ts

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

package/dist/rules/max-method-lines.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_MAX = 50;
+exports.default = (0, createRule_1.createRule)({
+    name: 'max-method-lines',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce a maximum length, in lines, for a named function or method. An inline callback is measured through the function hosting it.',
+        },
+        messages: {
+            tooManyLines: "'{{name}}' spans {{count}} lines (max {{max}}). A body that long is holding several ideas; give each one a name.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: { max: { type: 'integer', minimum: 1 } },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ max: DEFAULT_MAX }],
+    create(context, [{ max }]) {
+        const measure = (node, name, key) => {
+            const count = node.loc.end.line - node.loc.start.line + 1;
+            if (count <= max) {
+                return;
+            }
+            context.report({
+                node: key,
+                messageId: 'tooManyLines',
+                data: { name, count, max },
+            });
+        };
+        return {
+            MethodDefinition(node) {
+                if (node.key.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    return;
+                }
+                measure(node, node.key.name, node.key);
+            },
+            FunctionDeclaration(node) {
+                if (node.id === null) {
+                    return;
+                }
+                measure(node, node.id.name, node.id);
+            },
+            VariableDeclarator(node) {
+                if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    node.init === null ||
+                    (node.init.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+                        node.init.type !== utils_1.AST_NODE_TYPES.FunctionExpression)) {
+                    return;
+                }
+                measure(node.init, node.id.name, node.id);
+            },
+        };
+    },
+});

package/dist/rules/no-generic-error.d.ts

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

package/dist/rules/no-generic-error.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+/**
+ * The error types the language ships. Each says only "something went wrong",
+ * so every caller that wants to distinguish failures ends up matching on the
+ * message — a string the thrower is free to reword.
+ */
+const BUILT_IN_ERRORS = new Set([
+    'Error',
+    'EvalError',
+    'RangeError',
+    'ReferenceError',
+    'SyntaxError',
+    'TypeError',
+    'URIError',
+    'AggregateError',
+]);
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-generic-error',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow throwing the built-in error types. A named exception carries the failure in its type, where a caller can catch exactly it.',
+        },
+        messages: {
+            genericError: "Throwing '{{name}}' leaves the failure describable only by its message. Throw a named exception the caller can catch by type.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            ThrowStatement(node) {
+                if (node.argument.type !== utils_1.AST_NODE_TYPES.NewExpression ||
+                    node.argument.callee.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    !BUILT_IN_ERRORS.has(node.argument.callee.name)) {
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'genericError',
+                    data: { name: node.argument.callee.name },
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-public-mutable-props.d.ts

@@ -1,4 +1,7 @@
-declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"mutableProp", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+type Options = [{
+    parameterProperties: 'public' | 'all';
+}];
+declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"mutableProp", Options, unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
     name: string;
 };
 export default _default;

package/dist/rules/no-public-mutable-props.js

@@ -13,11 +13,14 @@ const keyName = (key) => {
     return 'property';
 };
 /**
- * A constructor parameter property the outside world can write to. Only
- * constructor parameter properties carry an accessibility modifier, so reading
- * one is enough to know the field is public.
+ * A constructor parameter property that can be written to. At `'all'` the
+ * visibility stops mattering: a `private` collaborator nobody marked readonly
+ * can still be swapped from inside, which is the same defect one wall further
+ * in. A parameter property with no modifier at all declares no field.
  */
-const isPublicMutable = (node) => node.accessibility === 'public' && !node.readonly;
+const isMutable = (node, scope) => !node.readonly &&
+    node.accessibility !== undefined &&
+    (scope === 'all' || node.accessibility === 'public');
 exports.default = (0, createRule_1.createRule)({
     name: 'no-public-mutable-props',
     meta: {
@@ -26,12 +29,20 @@ exports.default = (0, createRule_1.createRule)({
             description: 'Disallow public mutable class properties. Public state should be readonly to protect invariants and preserve encapsulation.',
         },
         messages: {
-            mutableProp: "Public property '{{name}}' is mutable. Make it readonly or expose it through a method that protects the invariant.",
+            mutableProp: "Property '{{name}}' is mutable. Make it readonly or expose it through a method that protects the invariant.",
         },
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    parameterProperties: { type: 'string', enum: ['public', 'all'] },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
-    defaultOptions: [],
-    create(context) {
+    defaultOptions: [{ parameterProperties: 'all' }],
+    create(context, [{ parameterProperties }]) {
         return {
             PropertyDefinition(node) {
                 if (node.readonly || isHidden(node.accessibility)) {
@@ -44,7 +55,7 @@ exports.default = (0, createRule_1.createRule)({
                 });
             },
             TSParameterProperty(node) {
-                if (!isPublicMutable(node)) {
+                if (!isMutable(node, parameterProperties)) {
                     return;
                 }
                 const target = node.parameter.type === utils_1.AST_NODE_TYPES.AssignmentPattern

package/dist/rules/no-self-mutation.d.ts

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

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

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+/**
+ * Nest calls these after the container has built the instance, so they finish
+ * a construction the constructor could not: a timer needs a running event
+ * loop, a pool needs a connection. Teardown is the same seam in reverse.
+ */
+const LIFECYCLE_HOOKS = [
+    'onModuleInit',
+    'onApplicationBootstrap',
+    'onModuleDestroy',
+    'beforeApplicationShutdown',
+    'onApplicationShutdown',
+];
+/**
+ * The field a write targets, when the target is a field of `this`. A computed
+ * write (`this[key] = value`) names no field and is left to other rules.
+ */
+const fieldOf = (target) => target.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+    !target.computed &&
+    target.object.type === utils_1.AST_NODE_TYPES.ThisExpression &&
+    target.property.type === utils_1.AST_NODE_TYPES.Identifier
+    ? target.property.name
+    : 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;
+};
+/** 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;
+};
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-self-mutation',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow writing to your own fields outside the constructor. An object that changes after construction is holding a lifecycle, not modelling a value.',
+        },
+        messages: {
+            mutatesSelf: "'this.{{name}}' is written after construction. Build a new object instead of letting this one change underneath its holders.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allowedMethods: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ allowedMethods: LIFECYCLE_HOOKS }],
+    create(context, [{ allowedMethods }]) {
+        const check = (node, target) => {
+            const name = fieldOf(target);
+            if (name === undefined || isDuringConstruction(node)) {
+                return;
+            }
+            const method = enclosingMethod(node);
+            if (method !== undefined && allowedMethods.includes(method)) {
+                return;
+            }
+            context.report({ node, messageId: 'mutatesSelf', data: { name } });
+        };
+        return {
+            AssignmentExpression(node) {
+                check(node, node.left);
+            },
+            UpdateExpression(node) {
+                check(node, node.argument);
+            },
+        };
+    },
+});

package/package.json

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