@tianjos/eslint-plugin-elegant 0.7.0 → 0.7.2

package/README.md

@@ -189,12 +189,36 @@ Public state should be `readonly` so callers cannot break an aggregate's
 invariants. A declared `private`/`protected` field is allowed, and so is any
 `readonly` member.
 
+A **decorated** property is allowed by default. `@Column`, `@IsString` and
+friends assign the field from outside the class, so `readonly` would be a lie
+and the property is framework shape rather than state the class chose to carry
+— a NestJS DTO or a TypeORM entity is a wall of them. Pass
+`{ ignoreDecorated: false }` to hold them to the same standard.
+
+```ts
+// passes — the framework populates these
+class BankDto {
+  @IsString() code: string;
+  @IsOptional() ispb_code?: string;
+}
+
+// reported — state the class chose to expose
+class Money {
+  amount = 0;
+}
+```
+
 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.
 
+`ignoreDecorated` deliberately does not reach parameter properties either. A
+decorator on a parameter is injection (`@Inject(TOKEN)`), which supplies a
+collaborator rather than populating a field, so it still has no business being
+reassignable. `max-class-fields` draws the same line for the same reason.
+
 This rule asks whether a field is *declared* changeable. Its behavioural
 counterpart is `no-self-mutation`, which asks whether anything actually
 changes it.
@@ -659,6 +683,74 @@ rules: {
 }
 ```
 
+### Adopting on an existing codebase
+
+The `recommended` config is written for the code you wish you had. Turning it
+on over code that already exists is a different exercise, and worth planning
+with numbers rather than discovering at the first `eslint .`.
+
+Measured over **1,261 production TypeScript files** across three NestJS
+services — a DTO-heavy, string-logging, TypeORM-backed shape this preset was
+built for:
+
+| Rule | Severity | Reports | Per file | In test files |
+| --- | --- | ---: | ---: | ---: |
+| `no-comments-in-function-body` | `error` | 5,559 | 4.41 | 2,589 |
+| `no-interpolated-log-message` | `error` | 1,941 | 1.54 | 0 |
+| `no-null` | `error` | 1,367 | 1.08 | 896 |
+| `no-type-assertion` | `error` | 524 | 0.42 | 935 |
+| `max-method-lines` | `warn` | 467 | 0.37 | 1 |
+| `max-params` | `warn` | 195 | 0.15 | 6 |
+| `no-null-return` | `error` | 194 | 0.15 | 2 |
+| `no-instanceof` | `error` | 179 | 0.14 | 0 |
+| `no-generic-error` | `error` | 163 | 0.13 | 17 |
+| `max-returns` | `warn` | 125 | 0.10 | 0 |
+| `no-public-mutable-props` | `error` | 116 | 0.09 | 0 |
+| `no-property-alias` | `error` | 111 | 0.09 | 1 |
+| `no-logic-in-constructor` | `error` | 98 | 0.08 | 0 |
+| `no-static-members` | `error` | 96 | 0.08 | 0 |
+| `no-anonymous-param-type` | `error` | 91 | 0.07 | 27 |
+| `no-self-mutation` | `error` | 66 | 0.05 | 0 |
+| `max-class-dependencies` | `warn` | 64 | 0.05 | 0 |
+| `max-class-fields` | `warn` | 57 | 0.05 | 0 |
+| `no-property-destructuring` | `error` | 53 | 0.04 | 0 |
+| `no-boolean-param` | `error` | 47 | 0.04 | 1 |
+| `max-class-methods` | `warn` | 40 | 0.03 | 0 |
+| `no-getters-setters` | `error` | 29 | 0.02 | 0 |
+| `no-else-return` | `error` | 13 | 0.01 | 0 |
+| `no-else-after-throw` | `error` | 8 | 0.01 | 0 |
+| **Total** | | **11,603** | **9.20** | |
+
+Four rules account for 81% of it, and they are the four whose principle has a
+boundary this plugin cannot see. `no-comments-in-function-body` asks you to
+rewrite a function, not edit a line. `no-interpolated-log-message` fires on
+whatever logging convention the project already chose, so on a codebase that
+logs with template strings it fires everywhere. `no-null` cannot tell a domain
+value from the wire format of a database column. `no-type-assertion` counts
+`x as unknown as T` twice, once per assertion, which is arguably correct.
+
+None of that makes them wrong — it makes them rules you adopt on purpose
+rather than inherit. **Enable the preset, then take the top of that table back
+to `warn` or `off` and work down it.** The rules below `no-type-assertion` sum
+to 1.75 per file, which is a starting point you can actually clear:
+
+```js
+rules: {
+  ...elegant.configs.recommended.rules,
+
+  // The four that need a plan of their own. Re-enable one at a time.
+  'elegant/no-comments-in-function-body': 'off',
+  'elegant/no-interpolated-log-message': 'warn',
+  'elegant/no-null': 'warn',
+  'elegant/no-type-assertion': 'warn',
+}
+```
+
+Numbers from one corpus are indicative, not universal. Run
+`npx eslint . --format json` on your own and sort by rule before deciding
+anything — the shape of your code decides which of these rules is a signal and
+which is a migration.
+
 ### Relaxing rules in test files
 
 Tests routinely use flag arguments and larger fixtures. Add a second config

package/dist/index.d.ts

@@ -28,6 +28,7 @@ declare const rules: {
     };
     'no-public-mutable-props': TSESLint.RuleModule<"mutableProp", [{
         parameterProperties: "public" | "all";
+        ignoreDecorated: boolean;
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };

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

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

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

@@ -21,6 +21,17 @@ const keyName = (key) => {
 const isMutable = (node, scope) => !node.readonly &&
     node.accessibility !== undefined &&
     (scope === 'all' || node.accessibility === 'public');
+/**
+ * A property a decorator maps to a table or a payload. `@Column`, `@IsString`
+ * and friends assign it from outside the class, so `readonly` would be a lie
+ * and the field is framework shape rather than state the class chose to carry.
+ *
+ * Deliberately does not reach parameter properties: a decorator on a parameter
+ * is injection (`@Inject(TOKEN)`), so the field is a genuine collaborator and
+ * still has no business being reassignable. `max-class-fields` draws the same
+ * line for the same reason.
+ */
+const isMapped = (node) => node.decorators.length > 0;
 exports.default = (0, createRule_1.createRule)({
     name: 'no-public-mutable-props',
     meta: {
@@ -36,18 +47,22 @@ exports.default = (0, createRule_1.createRule)({
                 type: 'object',
                 properties: {
                     parameterProperties: { type: 'string', enum: ['public', 'all'] },
+                    ignoreDecorated: { type: 'boolean' },
                 },
                 additionalProperties: false,
             },
         ],
     },
-    defaultOptions: [{ parameterProperties: 'all' }],
-    create(context, [{ parameterProperties }]) {
+    defaultOptions: [{ parameterProperties: 'all', ignoreDecorated: true }],
+    create(context, [{ parameterProperties, ignoreDecorated }]) {
         return {
             PropertyDefinition(node) {
                 if (node.readonly || isHidden(node.accessibility)) {
                     return;
                 }
+                if (ignoreDecorated && isMapped(node)) {
+                    return;
+                }
                 context.report({
                     node: node.key,
                     messageId: 'mutableProp',

package/package.json

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