@tianjos/eslint-plugin-elegant 0.4.0 → 0.5.0

package/README.md

@@ -90,6 +90,9 @@ The `recommended` config enables every custom rule plus two native ones,
 | `elegant/no-else-after-throw`          | custom | An `else` branch when the `then` branch always throws                           | `error`       |
 | `elegant/no-interpolated-log-message`  | custom | Log messages built by interpolation or concatenation                            | `error`       |
 | `elegant/max-returns`                  | custom | Functions returning from more places than `max`                                 | `warn` (max 3) |
+| `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) |
 | `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`       |
 
@@ -371,6 +374,148 @@ method's key, or the `const` or class field holding an arrow — falling back to
 `(anonymous)` for an inline callback. Configurable via `{ max: number }`
 (default `3`).
 
+#### `no-property-alias`
+
+A local whose whole job is to hold `obj.status` is a second name for state the
+object already exposes under a name of its own. It buys nothing and it costs a
+reader the hop of proving the two are the same value. Ask the object where you
+need the answer.
+
+```ts
+// reported
+const objStatus = obj.status;
+const authHeader = request.headers.authorization;
+const region = this.cognitoRegion;
+
+// passes
+obj.status;
+request.headers.authorization;
+this.cognitoRegion;
+```
+
+Only variable declarations are reported. `this.total = other.total` transfers
+state rather than aliasing it, and a property in an object literal
+(`{ id: dto.id }`) is how mappers are written; neither trips the rule.
+
+Four shapes are never reported, because in each of them the local is doing real
+work:
+
+- **A reassigned local.** `let status = obj.status` followed by
+  `status = 'EXPIRED'` holds mutable state that no member access stands in for.
+- **A local read inside a nested function.** TypeScript drops a narrowing of
+  `obj.prop` at the callback boundary but keeps it on a local, so inlining such
+  a declaration stops compiling:
+
+  ```ts
+  const status = obj.status;
+  if (status === undefined) return [];
+  return obj.items.map((n) => n + status.length); // needs the local
+  ```
+
+- **A chain that is not a plain run of `.prop` accesses.** A computed link
+  (`repo.save.mock.calls[1][0].metadata`) or a call in the middle
+  (`resolveDates(query).startDate`) is not a property of an object in hand, and
+  repeating it reads worse than naming it.
+- **An environment read.** `const topicArn = process.env.SNS_ERROR_TOPIC`
+  followed by a guard is fail-fast, and inlining it would read the environment
+  twice. Set `{ allowEnv: false }` to hold these to the same standard.
+
+Its sibling `no-property-destructuring` covers the same reach-in written as a
+pattern; together they say one thing, which is to ask the object.
+
+This rule is the mirror image of ESLint's native
+[`prefer-destructuring`](https://eslint.org/docs/latest/rules/prefer-destructuring),
+which reports `const status = obj.status` and asks you to write
+`const { status } = obj` instead. The two cannot both be on. `prefer-destructuring`
+is off by default, so there is nothing to undo unless you enabled it — and note
+that it only fires when the local and the property share a name, leaving the
+renaming majority (`const objStatus = obj.status`) unreported either way.
+
+#### `no-property-destructuring`
+
+`const { status, enabled } = obj` is `no-property-alias` written as a pattern:
+the object already names its own state, and the locals are a second set of
+names for it. This rule covers the pattern form, and only when the thing being
+destructured is an object you already hold — a name, `this`, or a run of plain
+`.prop` accesses rooted at one of those.
+
+```ts
+// reported
+const { status, enabled } = obj;
+const { access_token, expires_in } = response.data;
+const { region, poolId } = this.config;
+
+// passes — none of these was an object in hand
+function create({ id, name }) {}
+for (const { id, total } of rows) {}
+const { csvContent } = await service.exportCsv(query);
+const { startDate } = resolveDates(query);
+const [rows, total] = await repo.findAndCount();
+```
+
+Parameter patterns, loop bindings, and `catch` bindings are how you receive a
+value rather than reach into one, so they never come up. Neither does
+`ArrayPattern`: `const [rows, total] = ...` names the halves of a tuple that
+carries no names of its own.
+
+Four shapes are never reported, because in each of them the pattern is doing
+work no member access does:
+
+- **A rest element.** `const { authorization: _auth, ...safe } = headers`
+  constructs a new object by omission. There is nothing to inline it into.
+- **A default value.** `const { max = 3 } = options` inlines to
+  `options.max ?? 3`, repeating the fallback at every use site.
+- **A local read inside a nested function**, for the narrowing reason spelled
+  out under `no-property-alias`.
+- **A local reassigned later.** `let { status } = obj` followed by
+  `status = 'EXPIRED'` holds mutable state of its own.
+
+Renaming on the way out (`const { ingestion: failure } = row`) is still
+copying, and so is a single property. Width makes no difference: a pattern
+pulling four fields off an `input` is usually the sign that the method wanted
+the object, not the fields.
+
+#### `no-anonymous-param-type`
+
+`max-params` and `no-boolean-param` both push you towards an options object —
+and an options object typed inline is a bag that got away with it. The
+parameter count went down, the coupling did not, and the shape has nowhere to
+grow behaviour. Give it a name and it can become a value object; leave it
+anonymous and it stays a struct.
+
+```ts
+// reported
+private toResponse(group: { id: string; name: string; members: number }) {}
+async createFundingProducts(data: { originCode: string; productId: string }) {}
+chart(rows: Array<{ day: string; count: string }>) {}
+constructor(private readonly config: { host: string; port: number }) {}
+
+// passes
+async register(input: RegisterProposal) {}
+function charge(amount: number, currency: string) {}
+ingest(raw: Record<string, unknown>) {}
+```
+
+A shape counts wherever it hides in the annotation — on its own, in a union
+with `null`, intersected onto a named type, in an array, or inside a generic
+argument such as `Array<{ … }>`. A parameter is reported once however many
+shapes it holds, and each offending parameter is reported separately.
+Destructuring in the signature (`function create({ id }: { id: string })`)
+does not hide the bag, and neither does a default value.
+
+**Inline callbacks are never reported.** `res.body.items.map((i: { ccbNumber: string; total: number }) => i.total)`
+annotates whatever the callee yields; when that value has no type to borrow, an
+inline shape is the only way to type it at all.
+
+Configurable via `{ minMembers: number }` (default `2`). At the default, a
+one-property parameter like `opts?: { required?: boolean }` passes — naming a
+single field is usually ceremony rather than design. Set `minMembers: 1` to
+hold those to the same standard.
+
+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.
+
 ## Configuration
 
 ### Overriding thresholds

package/dist/index.d.ts

@@ -67,6 +67,19 @@ declare const rules: {
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };
+    'no-property-alias': TSESLint.RuleModule<"aliasesProperty", [{
+        allowEnv: boolean;
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-property-destructuring': TSESLint.RuleModule<"destructuresObject", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
+    'no-anonymous-param-type': TSESLint.RuleModule<"anonymousParamType", [{
+        minMembers: number;
+    }], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
 };
 type Plugin = {
     meta: {

package/dist/index.js

@@ -2,6 +2,7 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": 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_class_fields_1 = __importDefault(require("./rules/max-class-fields"));
 const max_returns_1 = __importDefault(require("./rules/max-returns"));
@@ -15,9 +16,15 @@ const no_interpolated_log_message_1 = __importDefault(require("./rules/no-interp
 const no_logic_in_constructor_1 = __importDefault(require("./rules/no-logic-in-constructor"));
 const no_null_1 = __importDefault(require("./rules/no-null"));
 const no_null_return_1 = __importDefault(require("./rules/no-null-return"));
+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"));
 const no_static_members_1 = __importDefault(require("./rules/no-static-members"));
 const no_type_assertion_1 = __importDefault(require("./rules/no-type-assertion"));
+// require() of a JSON file yields `any`, so there is no honest type to reach
+// for here. Importing it instead would put package.json inside the emitted
+// tree and move dist/index.js, which the "exports" map pins.
+// eslint-disable-next-line elegant/no-type-assertion
 const { name, version } = require('../package.json');
 const rules = {
     'no-boolean-param': no_boolean_param_1.default,
@@ -36,6 +43,9 @@ const rules = {
     'no-else-after-throw': no_else_after_throw_1.default,
     'no-interpolated-log-message': no_interpolated_log_message_1.default,
     'max-returns': max_returns_1.default,
+    '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,
 };
 const plugin = {
     meta: { name, version },
@@ -62,6 +72,9 @@ plugin.configs.recommended = {
         'elegant/no-comments-in-function-body': 'error',
         'elegant/no-else-after-throw': 'error',
         'elegant/no-interpolated-log-message': 'error',
+        'elegant/no-property-alias': 'error',
+        'elegant/no-property-destructuring': 'error',
+        'elegant/no-anonymous-param-type': ['error', { minMembers: 2 }],
         'max-params': ['warn', { max: 3 }],
         'no-else-return': ['error', { allowElseIf: false }],
     },

package/dist/rules/max-class-dependencies.js

@@ -39,9 +39,10 @@ const injected = (body, sourceCode) => {
 };
 const instantiated = (node, sourceCode) => {
     const root = sourceCode.getText(node.callee);
-    const args = node.typeArguments;
     return {
-        key: `${root}${args === undefined ? '' : sourceCode.getText(args)}`,
+        key: `${root}${node.typeArguments === undefined
+            ? ''
+            : sourceCode.getText(node.typeArguments)}`,
         root,
     };
 };
@@ -95,12 +96,11 @@ exports.default = (0, createRule_1.createRule)({
                 if (dependencies.size <= max) {
                     return;
                 }
-                const classNode = node.parent;
                 context.report({
-                    node: classNode.id ?? node,
+                    node: node.parent.id ?? node,
                     messageId: 'tooManyDependencies',
                     data: {
-                        name: classNode.id?.name ?? '(anonymous)',
+                        name: node.parent.id?.name ?? '(anonymous)',
                         count: dependencies.size,
                         max,
                         names: [...dependencies].join(', '),

package/dist/rules/max-class-fields.js

@@ -7,16 +7,16 @@ const isField = (member) => member.type === utils_1.AST_NODE_TYPES.PropertyDefin
     member.type === utils_1.AST_NODE_TYPES.TSAbstractPropertyDefinition ||
     member.type === utils_1.AST_NODE_TYPES.AccessorProperty;
 const named = (key, sourceCode) => key.type === utils_1.AST_NODE_TYPES.Identifier ? key.name : sourceCode.getText(key);
+/** Every property declared in the class body. */
+const declared = (member, sourceCode) => isField(member) && !member.static ? [named(member.key, sourceCode)] : [];
 /**
- * Properties declared in the class body. A decorated one is skipped by default:
- * `@Column`, `@IsString` and friends map a field to a table or a payload, which
- * is framework shape rather than state the class chose to carry.
+ * The same, minus the decorated ones: `@Column`, `@IsString` and friends map a
+ * field to a table or a payload, which is framework shape rather than state the
+ * class chose to carry.
  */
-const declared = (member, sourceCode, ignoreDecorated) => isField(member) &&
-    !member.static &&
-    !(ignoreDecorated && member.decorators.length > 0)
-    ? [named(member.key, sourceCode)]
-    : [];
+const declaredUndecorated = (member, sourceCode) => isField(member) && member.decorators.length > 0
+    ? []
+    : declared(member, sourceCode);
 /**
  * Constructor parameter properties. `ignoreDecorated` deliberately does not
  * reach them: a decorator on a parameter is injection (`@Inject(TOKEN)`), so the
@@ -55,21 +55,21 @@ exports.default = (0, createRule_1.createRule)({
     defaultOptions: [{ max: DEFAULT_MAX, ignoreDecorated: true }],
     create(context, [{ max, ignoreDecorated }]) {
         const sourceCode = context.sourceCode;
+        const fieldsOf = ignoreDecorated ? declaredUndecorated : declared;
         return {
             ClassBody(node) {
                 const fields = node.body.flatMap((member) => [
-                    ...declared(member, sourceCode, ignoreDecorated),
+                    ...fieldsOf(member, sourceCode),
                     ...promoted(member, sourceCode),
                 ]);
                 if (fields.length <= max) {
                     return;
                 }
-                const classNode = node.parent;
                 context.report({
-                    node: classNode.id ?? node,
+                    node: node.parent.id ?? node,
                     messageId: 'tooManyFields',
                     data: {
-                        name: classNode.id?.name ?? '(anonymous)',
+                        name: node.parent.id?.name ?? '(anonymous)',
                         count: fields.length,
                         max,
                         names: fields.join(', '),

package/dist/rules/max-class-methods.js

@@ -32,10 +32,9 @@ exports.default = (0, createRule_1.createRule)({
                 if (methods.length <= max) {
                     return;
                 }
-                const classNode = node.parent;
-                const name = classNode.id?.name ?? '(anonymous)';
+                const name = node.parent.id?.name ?? '(anonymous)';
                 context.report({
-                    node: classNode.id ?? node,
+                    node: node.parent.id ?? node,
                     messageId: 'tooManyMethods',
                     data: { name, count: methods.length, max },
                 });

package/dist/rules/max-returns.js

@@ -12,17 +12,16 @@ const nameOf = (node) => {
     if (node.id !== null) {
         return node.id.name;
     }
-    const parent = node.parent;
-    if ((parent.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
-        parent.type === utils_1.AST_NODE_TYPES.PropertyDefinition ||
-        parent.type === utils_1.AST_NODE_TYPES.Property) &&
-        !parent.computed &&
-        parent.key.type === utils_1.AST_NODE_TYPES.Identifier) {
-        return parent.key.name;
+    if ((node.parent.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
+        node.parent.type === utils_1.AST_NODE_TYPES.PropertyDefinition ||
+        node.parent.type === utils_1.AST_NODE_TYPES.Property) &&
+        !node.parent.computed &&
+        node.parent.key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.parent.key.name;
     }
-    if (parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
-        parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
-        return parent.id.name;
+    if (node.parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        node.parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.parent.id.name;
     }
     return '(anonymous)';
 };
@@ -58,14 +57,13 @@ exports.default = (0, createRule_1.createRule)({
             if (scope === undefined || scope.count <= max) {
                 return;
             }
-            const { node, count } = scope;
-            const signature = node.id ?? sourceCode.getFirstToken(node);
+            const signature = scope.node.id ?? sourceCode.getFirstToken(scope.node);
             context.report({
-                loc: (signature ?? node).loc,
+                loc: (signature ?? scope.node).loc,
                 messageId: 'tooManyReturns',
                 data: {
-                    name: nameOf(node),
-                    count,
+                    name: nameOf(scope.node),
+                    count: scope.count,
                     max,
                 },
             });

package/dist/rules/no-anonymous-param-type.d.ts

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

package/dist/rules/no-anonymous-param-type.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_MIN_MEMBERS = 2;
+const bindingOf = (param) => {
+    if (param.type === utils_1.AST_NODE_TYPES.TSParameterProperty) {
+        return bindingOf(param.parameter);
+    }
+    const target = param.type === utils_1.AST_NODE_TYPES.AssignmentPattern ? param.left : param;
+    switch (target.type) {
+        case utils_1.AST_NODE_TYPES.ArrayPattern:
+        case utils_1.AST_NODE_TYPES.Identifier:
+        case utils_1.AST_NODE_TYPES.ObjectPattern:
+        case utils_1.AST_NODE_TYPES.RestElement:
+            return target;
+        default:
+            return undefined;
+    }
+};
+const nameOf = (binding) => binding.type === utils_1.AST_NODE_TYPES.Identifier ? binding.name : '(destructured)';
+/** The type nodes a shape can hide inside, one level down. */
+const reachableFrom = (node) => {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeReference:
+            return node.typeArguments?.params ?? [];
+        case utils_1.AST_NODE_TYPES.TSUnionType:
+        case utils_1.AST_NODE_TYPES.TSIntersectionType:
+            return node.types;
+        case utils_1.AST_NODE_TYPES.TSArrayType:
+            return [node.elementType];
+        default:
+            return [];
+    }
+};
+/**
+ * The first anonymous shape of at least `minMembers` properties reachable from
+ * a type annotation. Shapes hide behind generic arguments as readily as they
+ * sit in the open — `Array<{ day; count }>` is as unnamed as `{ day; count }`.
+ */
+const shapeIn = (node, minMembers) => {
+    if (node.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
+        return node.members.length >= minMembers ? node : undefined;
+    }
+    for (const inner of reachableFrom(node)) {
+        const shape = shapeIn(inner, minMembers);
+        if (shape !== undefined) {
+            return shape;
+        }
+    }
+    return undefined;
+};
+/**
+ * Whether the signature is a function handed straight to a call. Such a
+ * parameter annotates whatever the callee yields — often an untyped response
+ * body — so an inline shape is the only way to type it at all.
+ */
+const isInlineCallback = (node) => (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+    node.type === utils_1.AST_NODE_TYPES.FunctionExpression) &&
+    node.parent.type === utils_1.AST_NODE_TYPES.CallExpression;
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-anonymous-param-type',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow parameters typed as an anonymous shape. Name the shape so it can carry behaviour instead of being a bag.',
+        },
+        messages: {
+            anonymousParamType: "Parameter '{{name}}' is typed as an anonymous shape of {{count}} properties. Name the shape so it can carry behaviour instead of being a bag.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    minMembers: { type: 'integer', minimum: 1 },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ minMembers: DEFAULT_MIN_MEMBERS }],
+    create(context, [{ minMembers }]) {
+        const check = (node) => {
+            if (isInlineCallback(node)) {
+                return;
+            }
+            for (const param of node.params) {
+                const binding = bindingOf(param);
+                if (binding === undefined) {
+                    continue;
+                }
+                const annotation = binding.typeAnnotation?.typeAnnotation;
+                if (annotation === undefined) {
+                    continue;
+                }
+                const shape = shapeIn(annotation, minMembers);
+                if (shape === undefined) {
+                    continue;
+                }
+                context.report({
+                    node: param,
+                    messageId: 'anonymousParamType',
+                    data: {
+                        name: nameOf(binding),
+                        count: shape.members.length,
+                    },
+                });
+            }
+        };
+        return {
+            ArrowFunctionExpression: check,
+            FunctionDeclaration: check,
+            FunctionExpression: check,
+            TSDeclareFunction: check,
+            TSEmptyBodyFunctionExpression: check,
+            TSFunctionType: check,
+            TSMethodSignature: check,
+        };
+    },
+});

package/dist/rules/no-interpolated-log-message.js

@@ -64,14 +64,13 @@ exports.default = (0, createRule_1.createRule)({
         const levels = new Set([...METHODS, ...methods]);
         return {
             CallExpression(node) {
-                const callee = node.callee;
-                if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
-                    callee.computed ||
-                    callee.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
-                    !levels.has(callee.property.name)) {
+                if (node.callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                    node.callee.computed ||
+                    node.callee.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    !levels.has(node.callee.property.name)) {
                     return;
                 }
-                const name = receiver(callee.object);
+                const name = receiver(node.callee.object);
                 if (name === undefined || !logging.has(name)) {
                     return;
                 }

package/dist/rules/no-logic-in-constructor.js

@@ -49,19 +49,18 @@ exports.default = (0, createRule_1.createRule)({
                     context.report({ node: statement, messageId: 'statement' });
                     continue;
                 }
-                const { expression } = statement;
-                if (isSuperCall(expression)) {
+                if (isSuperCall(statement.expression)) {
                     continue;
                 }
-                if (expression.type !== utils_1.AST_NODE_TYPES.AssignmentExpression ||
-                    expression.operator !== '=' ||
-                    !isThisMember(expression.left)) {
+                if (statement.expression.type !== utils_1.AST_NODE_TYPES.AssignmentExpression ||
+                    statement.expression.operator !== '=' ||
+                    !isThisMember(statement.expression.left)) {
                     context.report({ node: statement, messageId: 'statement' });
                     continue;
                 }
-                if (!isPlainValue(expression.right)) {
+                if (!isPlainValue(statement.expression.right)) {
                     context.report({
-                        node: expression.right,
+                        node: statement.expression.right,
                         messageId: 'computation',
                     });
                 }

package/dist/rules/no-null-return.js

@@ -18,10 +18,9 @@ exports.default = (0, createRule_1.createRule)({
     create(context) {
         return {
             ReturnStatement(node) {
-                const { argument } = node;
-                if (argument?.type === utils_1.AST_NODE_TYPES.Literal &&
-                    argument.value === null &&
-                    argument.raw === 'null') {
+                if (node.argument?.type === utils_1.AST_NODE_TYPES.Literal &&
+                    node.argument.value === null &&
+                    node.argument.raw === 'null') {
                     context.report({ node, messageId: 'noNullReturn' });
                 }
             },

package/dist/rules/no-null.js

@@ -2,6 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+/**
+ * A `null` sitting directly in a `return`. That shape is the domain of
+ * `no-null-return`, which reports it with its own message; reporting it here
+ * too would double up on one line of code.
+ */
+const isDirectReturn = (node) => node.parent.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
+    node.parent.argument === node;
 exports.default = (0, createRule_1.createRule)({
     name: 'no-null',
     meta: {
@@ -21,10 +28,7 @@ exports.default = (0, createRule_1.createRule)({
                 if (node.value !== null || node.raw !== 'null') {
                     return;
                 }
-                // Direct `return null;` is the domain of `no-null-return`.
-                const { parent } = node;
-                if (parent.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
-                    parent.argument === node) {
+                if (isDirectReturn(node)) {
                     return;
                 }
                 context.report({ node, messageId: 'noNull' });

package/dist/rules/no-property-alias.d.ts

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

package/dist/rules/no-property-alias.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const locals_1 = require("../utils/locals");
+const memberChain_1 = require("../utils/memberChain");
+const DEFAULT_ALLOW_ENV = true;
+/** Whether the chain reads `process.env.SOMETHING`. */
+const isEnvRead = (node) => node.object.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+    !node.object.computed &&
+    node.object.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+    node.object.object.name === 'process' &&
+    node.object.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+    node.object.property.name === 'env';
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-property-alias',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow locals that only rename a property of an object already in hand. Ask the object where the value is needed instead.',
+        },
+        messages: {
+            aliasesProperty: "'{{name}}' only renames '{{path}}'. Ask the object where you need the value instead of copying its state into a local.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allowEnv: { type: 'boolean' },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ allowEnv: DEFAULT_ALLOW_ENV }],
+    create(context, [{ allowEnv }]) {
+        return {
+            VariableDeclarator(node) {
+                if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    return;
+                }
+                if (node.init === null ||
+                    node.init.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                    !(0, memberChain_1.isObjectInHand)(node.init)) {
+                    return;
+                }
+                if (allowEnv && isEnvRead(node.init)) {
+                    return;
+                }
+                const [variable] = context.sourceCode.getDeclaredVariables(node);
+                if (variable === undefined ||
+                    (0, locals_1.isReassigned)(variable) ||
+                    (0, locals_1.escapesIntoFunction)(variable)) {
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'aliasesProperty',
+                    data: {
+                        name: node.id.name,
+                        path: context.sourceCode.getText(node.init),
+                    },
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-property-destructuring.d.ts

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

package/dist/rules/no-property-destructuring.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const locals_1 = require("../utils/locals");
+const memberChain_1 = require("../utils/memberChain");
+/**
+ * Whether the pattern collects the properties it does not name into a rest
+ * object. That is construction by omission, not a copy of state anyone can
+ * replace with a member access.
+ */
+const hasRestElement = (node) => node.properties.some((property) => property.type === utils_1.AST_NODE_TYPES.RestElement);
+/**
+ * Whether any property carries a default. `options.max ?? 3` repeats the
+ * fallback at every use site, so the pattern is holding a decision rather than
+ * just a copy.
+ */
+const hasDefault = (node) => node.properties.some((property) => property.type === utils_1.AST_NODE_TYPES.Property &&
+    property.value.type === utils_1.AST_NODE_TYPES.AssignmentPattern);
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-property-destructuring',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow destructuring an object already in hand. Ask the object where each value is needed instead.',
+        },
+        messages: {
+            destructuresObject: "Destructuring '{{name}}' copies its state into {{count}} locals. Ask the object where you need each value instead.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            ObjectPattern(node) {
+                if (node.parent.type !== utils_1.AST_NODE_TYPES.VariableDeclarator ||
+                    node.parent.init === null ||
+                    !(0, memberChain_1.isObjectInHand)(node.parent.init)) {
+                    return;
+                }
+                if (hasRestElement(node) || hasDefault(node)) {
+                    return;
+                }
+                const variables = context.sourceCode.getDeclaredVariables(node.parent);
+                if (variables.some((variable) => (0, locals_1.isReassigned)(variable) || (0, locals_1.escapesIntoFunction)(variable))) {
+                    return;
+                }
+                context.report({
+                    node: node.parent,
+                    messageId: 'destructuresObject',
+                    data: {
+                        name: context.sourceCode.getText(node.parent.init),
+                        count: node.properties.length,
+                    },
+                });
+            },
+        };
+    },
+});

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

@@ -12,6 +12,12 @@ 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.
+ */
+const isPublicMutable = (node) => node.accessibility === 'public' && !node.readonly;
 exports.default = (0, createRule_1.createRule)({
     name: 'no-public-mutable-props',
     meta: {
@@ -38,9 +44,7 @@ exports.default = (0, createRule_1.createRule)({
                 });
             },
             TSParameterProperty(node) {
-                // Only constructor parameter properties carry an accessibility modifier.
-                if (node.accessibility !== 'public' ||
-                    node.readonly) {
+                if (!isPublicMutable(node)) {
                     return;
                 }
                 const target = node.parameter.type === utils_1.AST_NODE_TYPES.AssignmentPattern

package/dist/utils/locals.d.ts

@@ -0,0 +1,13 @@
+import { TSESLint } from '@typescript-eslint/utils';
+/**
+ * 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
+ * of the object's state to begin with.
+ */
+export declare const isReassigned: (variable: TSESLint.Scope.Variable) => boolean;
+/**
+ * Whether the variable is read from inside a nested function. TypeScript drops
+ * a narrowing of `obj.prop` at the callback boundary but keeps it on a local,
+ * so such a declaration is load-bearing: inlining it stops compiling.
+ */
+export declare const escapesIntoFunction: (variable: TSESLint.Scope.Variable) => boolean;

package/dist/utils/locals.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+ * of the object's state to begin with.
+ */
+const isReassigned = (variable) => variable.references.some((reference) => reference.isWrite() && !reference.init);
+exports.isReassigned = isReassigned;
+/**
+ * Whether the variable is read from inside a nested function. TypeScript drops
+ * a narrowing of `obj.prop` at the callback boundary but keeps it on a local,
+ * so such a declaration is load-bearing: inlining it stops compiling.
+ */
+const escapesIntoFunction = (variable) => variable.references.some((reference) => {
+    let scope = reference.from;
+    while (scope !== null && scope !== variable.scope) {
+        if (scope.type === 'function') {
+            return true;
+        }
+        scope = scope.upper;
+    }
+    return false;
+});
+exports.escapesIntoFunction = escapesIntoFunction;

package/dist/utils/memberChain.d.ts

@@ -0,0 +1,8 @@
+import { TSESTree } from '@typescript-eslint/utils';
+/**
+ * Whether the expression denotes an object the reader already holds: a name,
+ * `this`, or a run of plain `.prop` accesses rooted at one of those. A computed
+ * link (`calls[1][0].metadata`) or a call in the middle
+ * (`resolveDates(query).startDate`) fails — nobody gains by inlining those.
+ */
+export declare const isObjectInHand: (node: TSESTree.Node) => boolean;

package/dist/utils/memberChain.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isObjectInHand = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+/**
+ * Whether the expression denotes an object the reader already holds: a name,
+ * `this`, or a run of plain `.prop` accesses rooted at one of those. A computed
+ * link (`calls[1][0].metadata`) or a call in the middle
+ * (`resolveDates(query).startDate`) fails — nobody gains by inlining those.
+ */
+const isObjectInHand = (node) => {
+    let current = node;
+    while (current.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        if (current.computed) {
+            return false;
+        }
+        current = current.object;
+    }
+    return (current.type === utils_1.AST_NODE_TYPES.Identifier ||
+        current.type === utils_1.AST_NODE_TYPES.ThisExpression);
+};
+exports.isObjectInHand = isObjectInHand;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianjos/eslint-plugin-elegant",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -41,6 +41,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "lint": "npm run build && eslint .",
     "typecheck": "tsc -p tsconfig.test.json",
     "test": "jest",
     "release": "standard-version",