@tianjos/eslint-plugin-elegant 0.8.0 → 0.10.0

package/README.md

@@ -63,14 +63,33 @@ export default [
 ];
 ```
 
-A complete, copy-pasteable example (including test-file overrides) lives in
+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).
+
+Two more configs exist for the files a preset should not judge the same way —
+`tests` and `off`. See [Relaxing rules in test files](#relaxing-rules-in-test-files)
+and [Generated and scaffolded files](#generated-and-scaffolded-files).
+
+A complete, copy-pasteable example (including those 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 four configs. Two are presets — `recommended` and `starter`
+— 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).
+- **`tests`** — an override, not a preset: the eight rules a spec legitimately
+  trips, off. See [Relaxing rules in test files](#relaxing-rules-in-test-files).
+- **`off`** — an override too: every rule disabled, for generated files. See
+  [Generated and scaffolded files](#generated-and-scaffolded-files).
 
 | Rule                                   | Source | What it catches                                                                 | `recommended` |
 | -------------------------------------- | ------ | ------------------------------------------------------------------------------- | ------------- |
@@ -78,7 +97,8 @@ The `recommended` config enables every custom rule plus two native ones,
 | `elegant/max-class-methods`            | custom | Classes with more methods than the configured `max` (constructors excluded)     | `warn` (max 10) |
 | `elegant/max-class-dependencies`       | custom | Classes depending on more distinct collaborators than `max` (constructor injections plus `new`) | `warn` (max 4) |
 | `elegant/max-class-fields`             | custom | Classes holding more instance fields than `max` (declared fields plus parameter properties) | `warn` (max 5) |
-| `elegant/no-type-assertion`            | custom | `value as T` and `<T>value` assertions (`as const` is allowed)                  | `error`       |
+| `elegant/no-type-assertion`            | custom | `value as T`, `<T>value`, and `value!` assertions (`as const` is allowed)       | `error`       |
+| `elegant/no-any-return`                | custom | `any` (or `Promise<any>`) declared as a function's return type                  | `error`       |
 | `elegant/no-null-return`               | custom | `return null` statements                                                        | `error`       |
 | `elegant/no-public-mutable-props`      | custom | Public, non-`readonly` class properties and public constructor parameter props  | `error`       |
 | `elegant/no-logic-in-constructor`      | custom | Any constructor code beyond `this.field = value` stores and a `super(...)` call  | `error`       |
@@ -178,10 +198,74 @@ Assertions silence the type checker. Reach for a type guard, a generic, or a
 correctly typed value instead. `as const` is permitted because it narrows rather
 than widens.
 
+All three syntactic forms are the same act, so all three are reported: `value
+as T`, `<T>value`, and the non-null operator `value!`. The last one is the one
+worth naming, because it is the cheapest to type and the most expensive to be
+wrong about — `entity.rate!` compiles whether the column is nullable, whether
+the driver hands back a string, or whether the row simply has no value. Narrow
+it with a check that throws, or correct the type if it was never nullable:
+
+```ts
+// reported
+const rate = origin.subsequentRate!;
+
+// intended
+const requireRate = (origin: Origin): number => {
+  if (origin.subsequentRate === undefined) {
+    throw new MissingRateError(origin.code);
+  }
+  return origin.subsequentRate;
+};
+```
+
+Pairs with [`no-any-return`](#no-any-return), which closes the way around it.
+
+#### `no-any-return`
+
+A function whose declared return type is `any` widens every value that passes
+through it. That is a type assertion — the caller writes `const body: T =
+parse(raw)` and the checker agrees — except it is invisible: `as T` is
+greppable at the call site, an `any` return is not.
+
+This is the shape `no-type-assertion` pushes code into if nothing catches it.
+The cast does not disappear; it moves one call deeper and stops being reviewable.
+
+```ts
+// reported — every caller's type is asserted for them
+const readJson = async (response: Response): Promise<any> => response.json();
+
+// intended — the caller narrows, or supplies the type it is claiming
+const readJson = async (response: Response): Promise<unknown> => response.json();
+const request = async <T>(path: string): Promise<T> => fetch(path).then(parse);
+```
+
+Return position only. `any` on a *parameter* is a different (lesser) defect and
+belongs to [`@typescript-eslint/no-explicit-any`](https://typescript-eslint.io/rules/no-explicit-any);
+this rule stays narrow so it can ship in the preset without requiring
+type-aware linting. `Promise<any>` counts, because awaiting it is not a
+narrowing step.
+
 #### `no-null-return`
 
-Keeps absence out of return values; model it with an explicit domain type or
-throw.
+Keeps absence out of return values. Throw when the value must exist, or return
+an object that answers for the absent case — a null object, a domain type with
+a "nothing found" state.
+
+An empty collection models absence only where the return type *was already* a
+collection. Wrapping a single value in a zero-or-one array to dodge this rule
+is a null in a box: the type now promises a list it will never have more than
+one of, and every caller loops over something that is really an `if`.
+
+```ts
+// reported
+function decide(status: number): Retry | null { ... }
+
+// a null in a box — the type lies, and callers write a loop that runs once
+function decide(status: number): Retry[] { ... }
+
+// intended
+function decide(status: number): Retry { return matched ?? Retry.none(); }
+```
 
 #### `no-public-mutable-props`
 
@@ -231,6 +315,49 @@ predictable. Parameter properties (`constructor(private readonly x: T)`) and a
 leading `super(...)` are allowed; computed right-hand sides (`this.x = x * 2`,
 `this.items = items.slice()`) and any non-assignment statement are flagged.
 
+**On a class a DI container builds**, the remedy the rule names does not exist:
+nobody calls `new` on a Nest provider, so there is no static factory to move
+the work to. The tempting move is to push it into a lifecycle hook, and that
+trades one rule for a worse invariant — the field stops being `readonly` and
+starts being assigned some time after construction:
+
+```ts
+// reported
+constructor(private readonly config: ConfigService) {
+  this.baseUrl = this.config.getOrThrow('COBRANSAAS_BASE_URL');
+}
+
+// worse: the field is now mutable and empty until a hook runs
+private baseUrl: string;
+onModuleInit() {
+  this.baseUrl = this.config.getOrThrow('COBRANSAAS_BASE_URL');
+}
+```
+
+Resolve the config where the module is wired, and inject the result. The
+constructor goes back to storing an argument, the field stays `readonly`, and a
+missing variable fails at boot instead of on the first request:
+
+```ts
+// cobransaas.module.ts
+providers: [
+  {
+    provide: COBRANSAAS_SETTINGS,
+    inject: [ConfigService],
+    useFactory: (config: ConfigService): CobransaasSettings => ({
+      baseUrl: config.getOrThrow('COBRANSAAS_BASE_URL'),
+      clientId: config.getOrThrow('COBRANSAAS_CLIENT_ID'),
+    }),
+  },
+]
+
+// cobransaas-http-client.service.ts
+constructor(
+  @Inject(COBRANSAAS_SETTINGS)
+  private readonly settings: CobransaasSettings,
+) {}
+```
+
 #### `no-getters-setters`
 
 Getters and setters turn objects into data bags; prefer methods that expose
@@ -245,7 +372,7 @@ 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
+Three uses are allowed by default, because in each of them TypeScript leaves no
 polymorphic alternative to reach for.
 
 **A self-guard** — `other instanceof Money` inside `class Money`. Value
@@ -261,6 +388,22 @@ 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 }`.
 
+**A declared type guard** — a function whose return type is a predicate,
+`value is X`. Some classes are nominal and offer no discriminant to switch on:
+a framework exception, a value object from another module, an `Error` subclass.
+The check has to happen somewhere, and a `value is X` signature is the one
+place it states what it is doing — the answer leaves as a narrowed type instead
+of a bare boolean, the class name is written once, and the project ends up with
+one greppable guard per class rather than an `instanceof` in the middle of a
+method. Only the innermost enclosing function counts, so a guard cannot lend
+its exemption to the code that follows it. Off via `{ allowTypeGuards: false }`.
+
+This exists so the cheapest way out of the rule is also the honest one. Without
+it, the reachable workaround is structural duck typing — `'toDate' in value`
+instead of `value instanceof IsoDate` — which passes the linter, passes for any
+object that happens to carry the member, and is strictly worse than what it
+replaced.
+
 ```ts
 // allowed
 class Money {
@@ -271,12 +414,19 @@ class Money {
 try { charge(); } catch (error) {
   if (error instanceof HttpException) { log(error.getStatus()); }
 }
+export const isIsoDate = (value: unknown): value is IsoDate =>
+  value instanceof IsoDate;
 
 // still reported
 if (shape instanceof Circle) { draw(); }
 function handle(error: HttpException) { return error instanceof HttpException; }
+function isIsoDate(value: unknown): boolean { return value instanceof IsoDate; }
 ```
 
+The last one is the near miss worth spelling out: a function that returns
+`boolean` declares nothing. It is a guard only once the signature says
+`value is IsoDate`.
+
 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
@@ -768,22 +918,44 @@ 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 |
 
-  // 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',
+Promote them back one at a time as you clear them, and switch to
+`recommended` once nothing is left:
+
+```js
+rules: {
+  ...elegant.configs.starter.rules,
+  'elegant/no-null': 'error',   // cleared, so hold the line
 }
 ```
 
+Two rules arrived after that measurement and are not in the table above:
+`no-any-return`, and `no-type-assertion`'s coverage of the non-null operator
+`x!`. Measured separately over a fourth service — 135 production files, same
+shape — they are tail rules, not migrations: **2** reports for `x!` and **0**
+for `no-any-return`. The interesting number is from the same repository *after*
+a full pass to green under `starter`: the tree linted clean, and the two rules
+still found one `Promise<any>` return that had absorbed a cast the pass had
+removed. They are cheap to adopt and they close a door the other rules push
+people through.
+
 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
@@ -791,29 +963,63 @@ which is a migration.
 
 ### Relaxing rules in test files
 
-Tests routinely use flag arguments and larger fixtures. Add a second config
-block scoped to your spec globs:
+Spread `tests` in a config block scoped to your spec globs:
 
 ```js
 {
   files: ['**/*.spec.ts', '**/*.test.ts', '**/*.e2e-spec.ts'],
-  rules: {
-    'elegant/no-boolean-param': 'off',
-    'elegant/max-class-methods': 'off',
-    'elegant/max-class-dependencies': 'off',
-    'elegant/max-class-fields': 'off',
-    'elegant/no-comments-in-function-body': 'off',
-    'max-params': 'off',
-  },
+  rules: { ...elegant.configs.tests.rules },
 }
 ```
 
+It turns off eight rules, and the list is a measurement rather than a taste.
+Over the corpus above, these are the rules that actually report inside test
+files, each for a reason that holds there and nowhere else:
+
+| Rule | Reports in tests | Why it holds in a spec |
+| --- | ---: | --- |
+| `no-comments-in-function-body` | 2,589 | a spec narrates the scenario |
+| `no-type-assertion` | 935 | a mock asserts a type over a partial object |
+| `no-null` | 896 | a fixture mirrors a nullable column |
+| `no-anonymous-param-type` | 27 | a fixture builder takes an inline shape |
+| `no-generic-error` | 17 | `throw new Error('boom')` as a failure stub |
+| `max-params` | 6 | a setup helper |
+| `no-null-return` | 2 | a fixture returns absence |
+| `no-boolean-param` | 1 | `make*(withRefunds: true)` names the case under test |
+
+What the list leaves out is deliberate. `max-class-fields`, `max-returns`,
+`no-static-members`, `no-interpolated-log-message` and the other class-shape
+rules report **zero** times in specs on that corpus, so switching them off buys
+nothing today and costs you the report on the day a spec finally earns one.
+Turn a rule off when you have seen it fire and disagreed — not in advance.
+
+### Generated and scaffolded files
+
+Some files are not written by hand: a migration the TypeORM CLI emits, a script
+that generates an OpenAPI document and talks to an operator through `console`.
+Judging them by rules meant for domain code produces churn in files nobody
+should reopen. Spread `off`, which is every rule this plugin ships, disabled:
+
+```js
+{
+  files: ['src/database/migrations/**/*.ts', 'utils/**/*.ts'],
+  rules: { ...elegant.configs.off.rules },
+}
+```
+
+Derived from the plugin's own rule list rather than spelled out in your config,
+so a rule added in a later version arrives already silent in those files. A
+hand-rolled equivalent — mapping over `Object.keys(elegant.rules)` in your own
+config — goes stale the moment it is written.
+
 ## Compatibility
 
 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`,
+`starter`, `tests`, and `off`. All three load paths are exercised against the built output by
+`tests/dist.test.ts`.
 
 ## Prior art
 

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import type { TSESLint } from '@typescript-eslint/utils';
 declare const rules: {
+    'no-any-return': TSESLint.RuleModule<"anyReturn", [], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
     'no-boolean-param': TSESLint.RuleModule<"booleanParam", [], unknown, TSESLint.RuleListener> & {
         name: string;
     };
@@ -20,7 +23,7 @@ declare const rules: {
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };
-    'no-type-assertion': TSESLint.RuleModule<"noAssertion", [], unknown, TSESLint.RuleListener> & {
+    'no-type-assertion': TSESLint.RuleModule<"noAssertion" | "nonNullAssertion", [], unknown, TSESLint.RuleListener> & {
         name: string;
     };
     'no-null-return': TSESLint.RuleModule<"noNullReturn", [], unknown, TSESLint.RuleListener> & {
@@ -43,6 +46,7 @@ declare const rules: {
     'no-instanceof': TSESLint.RuleModule<"noInstanceof", [{
         allowSelfGuard: boolean;
         allowCaughtValues: boolean;
+        allowTypeGuards: boolean;
     }], unknown, TSESLint.RuleListener> & {
         name: string;
     };

package/dist/index.js

@@ -3,6 +3,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 no_any_return_1 = __importDefault(require("./rules/no-any-return"));
 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"));
@@ -30,6 +31,7 @@ const no_type_assertion_1 = __importDefault(require("./rules/no-type-assertion")
 // eslint-disable-next-line elegant/no-type-assertion
 const { name, version } = require('../package.json');
 const rules = {
+    'no-any-return': no_any_return_1.default,
     'no-boolean-param': no_boolean_param_1.default,
     'max-class-methods': max_class_methods_1.default,
     'max-class-dependencies': max_class_dependencies_1.default,
@@ -62,6 +64,7 @@ plugin.configs.recommended = {
     name: 'elegant/recommended',
     plugins: { elegant: plugin },
     rules: {
+        'elegant/no-any-return': 'error',
         'elegant/no-boolean-param': 'error',
         'elegant/max-class-methods': ['warn', { max: 10 }],
         'elegant/max-class-dependencies': ['warn', { max: 4 }],
@@ -88,5 +91,73 @@ 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,
+    },
+};
+/**
+ * Every rule this plugin ships, off. For files nobody writes by hand: a
+ * migration the TypeORM CLI scaffolds, a build script that talks to an
+ * operator through `console`. Derived from `rules` here rather than listed in
+ * the consumer's config, so a rule added in a later version arrives already
+ * silent in those files instead of reporting on generated code.
+ */
+plugin.configs.off = {
+    name: 'elegant/off',
+    plugins: { elegant: plugin },
+    rules: Object.fromEntries(Object.keys(rules).map((rule) => [`elegant/${rule}`, 'off'])),
+};
+/**
+ * The rules a spec legitimately trips, off — and only those.
+ *
+ * Which ones those are is a measurement, not a taste: over the corpus in
+ * "Adopting on an existing codebase", these eight are the rules that fire
+ * inside test files, each for a reason that holds there and nowhere else. A
+ * mock has to assert a type over a partial object, a fixture mirrors a
+ * nullable column, `make*(withRefunds: true)` names the scenario under test,
+ * and a spec narrates.
+ *
+ * The rules kept out of this list are kept out on purpose. `max-class-fields`,
+ * `max-returns`, `no-static-members` and the rest report zero times in specs
+ * on that corpus, so turning them off buys nothing and costs the report on the
+ * day a spec finally earns one.
+ */
+plugin.configs.tests = {
+    name: 'elegant/tests',
+    plugins: { elegant: plugin },
+    rules: {
+        'elegant/no-comments-in-function-body': 'off',
+        'elegant/no-type-assertion': 'off',
+        'elegant/no-null': 'off',
+        'elegant/no-null-return': 'off',
+        'elegant/no-generic-error': 'off',
+        'elegant/no-boolean-param': 'off',
+        'elegant/no-anonymous-param-type': 'off',
+        'max-params': 'off',
+    },
+};
 plugin.default = plugin;
 module.exports = plugin;

package/dist/rules/no-any-return.d.ts

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

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const isNamed = (node, name) => node.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+    node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+    node.typeName.name === name;
+/**
+ * What a `Promise<T>` resolves to, or the node itself. `Promise<any>` is the
+ * same promise to the caller as `any` — awaiting it is not a narrowing step.
+ */
+const awaited = (node) => isNamed(node, 'Promise') && node.type === utils_1.AST_NODE_TYPES.TSTypeReference
+    ? (node.typeArguments?.params[0] ?? node)
+    : node;
+exports.default = (0, createRule_1.createRule)({
+    name: 'no-any-return',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow `any` as a return type. A function that returns `any` widens every value that passes through it, which is a type assertion the reader cannot see.',
+        },
+        messages: {
+            anyReturn: 'Returning `any` asserts every caller\'s type for them, invisibly. Return `unknown` and make the caller narrow, or a generic the caller supplies.',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const check = (node) => {
+            const annotation = node.returnType?.typeAnnotation;
+            if (annotation !== undefined &&
+                awaited(annotation).type === utils_1.AST_NODE_TYPES.TSAnyKeyword) {
+                context.report({ node: annotation, messageId: 'anyReturn' });
+            }
+        };
+        return {
+            ArrowFunctionExpression: check,
+            FunctionDeclaration: check,
+            FunctionExpression: check,
+            TSCallSignatureDeclaration: check,
+            TSConstructSignatureDeclaration: check,
+            TSDeclareFunction: check,
+            TSEmptyBodyFunctionExpression: check,
+            TSFunctionType: check,
+            TSMethodSignature: check,
+        };
+    },
+});

package/dist/rules/no-instanceof.d.ts

@@ -1,7 +1,10 @@
-type Options = [{
-    allowSelfGuard: boolean;
-    allowCaughtValues: boolean;
-}];
+type Options = [
+    {
+        allowSelfGuard: boolean;
+        allowCaughtValues: boolean;
+        allowTypeGuards: boolean;
+    }
+];
 declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noInstanceof", Options, unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
     name: string;
 };

package/dist/rules/no-instanceof.js

@@ -4,6 +4,26 @@ 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");
+const FUNCTIONS = new Set([
+    utils_1.AST_NODE_TYPES.ArrowFunctionExpression,
+    utils_1.AST_NODE_TYPES.FunctionDeclaration,
+    utils_1.AST_NODE_TYPES.FunctionExpression,
+]);
+/**
+ * Whether the check sits inside a function that declares a type predicate.
+ * A `value is X` signature is the one place a nominal check states what it is
+ * doing: the answer leaves as a narrowed type rather than as a bare boolean,
+ * every call site reads the class name once, and the project ends up with one
+ * greppable guard per class instead of an `instanceof` in the middle of a
+ * method. Only the innermost function counts, so a guard cannot lend its
+ * exemption to code that merely follows it.
+ */
+const isInsideTypeGuard = (node) => {
+    const fn = (0, ancestors_1.closestAncestor)(node, (candidate) => FUNCTIONS.has(candidate.type));
+    return (fn !== undefined &&
+        'returnType' in fn &&
+        fn.returnType?.typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypePredicate);
+};
 /** 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 ||
@@ -26,10 +46,10 @@ exports.default = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Disallow the `instanceof` operator. Type discrimination breaks polymorphism; let the object decide via a method instead.',
+            description: 'Disallow the `instanceof` operator. Type discrimination breaks polymorphism; let the object decide via a method instead. A check that has no polymorphic form belongs in a declared `value is X` type guard.',
         },
         messages: {
-            noInstanceof: 'Avoid `instanceof`. Replace type discrimination with a polymorphic method on the object.',
+            noInstanceof: 'Avoid `instanceof`. Replace type discrimination with a polymorphic method on the object. If the class is nominal and offers no discriminant, move the check into a function that declares `value is {{name}}` and call that.',
         },
         schema: [
             {
@@ -37,24 +57,34 @@ exports.default = (0, createRule_1.createRule)({
                 properties: {
                     allowSelfGuard: { type: 'boolean' },
                     allowCaughtValues: { type: 'boolean' },
+                    allowTypeGuards: { type: 'boolean' },
                 },
                 additionalProperties: false,
             },
         ],
     },
-    defaultOptions: [{ allowSelfGuard: true, allowCaughtValues: true }],
-    create(context, [{ allowSelfGuard, allowCaughtValues }]) {
+    defaultOptions: [
+        { allowSelfGuard: true, allowCaughtValues: true, allowTypeGuards: true },
+    ],
+    create(context, [{ allowSelfGuard, allowCaughtValues, allowTypeGuards }]) {
         return {
             'BinaryExpression[operator="instanceof"]'(node) {
                 if (allowSelfGuard && isSelfGuard(node)) {
                     return;
                 }
+                if (allowTypeGuards && isInsideTypeGuard(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' });
+                context.report({
+                    node,
+                    messageId: 'noInstanceof',
+                    data: { name: context.sourceCode.getText(node.right) },
+                });
             },
         };
     },

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

@@ -7,10 +7,10 @@ exports.default = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Disallow returning null. Model absence with an explicit type, an Optional/Maybe, or by throwing.',
+            description: 'Disallow returning null. Throw when the value must exist, return an object that answers for the absent case, or — when the return type is already a collection — an empty one.',
         },
         messages: {
-            noNullReturn: 'Returning null leaks absence into callers. Return an explicit empty value, a domain type, or throw.',
+            noNullReturn: 'Returning null leaks absence into callers. Throw if the value must exist, or return an object that answers for the absent case. An empty collection models absence only where the return type was already a collection — a zero-or-one array is a null in a box.',
         },
         schema: [],
     },

package/dist/rules/no-type-assertion.d.ts

@@ -1,4 +1,5 @@
-declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noAssertion", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+type MessageIds = 'noAssertion' | 'nonNullAssertion';
+declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<MessageIds, [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
     name: string;
 };
 export default _default;

package/dist/rules/no-type-assertion.js

@@ -10,10 +10,11 @@ exports.default = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Disallow type assertions, which bypass the type checker. Prefer type guards, generics, or honest types. `as const` is allowed.',
+            description: 'Disallow type assertions, which bypass the type checker: `as T`, `<T>x`, and the non-null operator `x!`. Prefer type guards, generics, or honest types. `as const` is allowed.',
         },
         messages: {
             noAssertion: 'Type assertions silence the type checker. Use a type guard, a generic, or a correctly typed value instead.',
+            nonNullAssertion: '`!` asserts away a nullable the type says is there. Narrow it with a check that throws, or correct the type if it was never nullable.',
         },
         schema: [],
     },
@@ -29,6 +30,9 @@ exports.default = (0, createRule_1.createRule)({
             TSTypeAssertion(node) {
                 context.report({ node, messageId: 'noAssertion' });
             },
+            TSNonNullExpression(node) {
+                context.report({ node, messageId: 'nonNullAssertion' });
+            },
         };
     },
 });

package/package.json

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