@sarj/eslint-plugin 16.2.4 → 16.2.5

package/dist/index.cjs

@@ -17622,15 +17622,16 @@ var prefer_nullish_filter_predicate_default = createRule({
 var import_utils103 = require("@typescript-eslint/utils");
 var ts11 = __toESM(require("typescript"), 1);
 var PREFER_AWAIT_IN_ASYNC_RETURN_DOCUMENTATION = {
-  summary: "Prefer explicit `await` when an async function directly returns one typed Promise `.then` transform.",
-  rationale: "Mixing a directly returned Promise callback into otherwise async control flow makes sequencing and failures harder to read.",
+  summary: "Prefer explicit `await` for proven Promise `.then` calls; the default scope checks direct async returns.",
+  rationale: "Promise callback chains mix explicit async control flow with nested callbacks, making sequencing and failure handling harder to read.",
   remediation: "Consider awaiting the Promise and returning the transformed value with ordinary async statements. Preserve catch boundaries, callback behavior, and observable scheduling when rewriting manually.",
   category: "maintainability",
   since: "15.6.3",
   limitations: [
-    "Only a single directly returned `.then` call with an inline callback is checked.",
-    "The receiver must be proven Promise-like by TypeScript; an earlier chain can still produce that receiver. Untyped receivers, rejection handlers and named callbacks are excluded. This is not the upstream return-await policy and no scheduling equivalence is promised.",
-    "Direct loader callbacks passed to resolved `React.lazy` and `next/dynamic` imports are excluded because returning the module Promise is their framework contract."
+    "The default async-return scope checks one directly returned `.then` call with an inline callback. The all-promise-calls scope checks direct calls to built-in Promise/PromiseLike.then, including optional and literal-computed calls, without automatic rewrites.",
+    "The receiver must be proven Promise-like by TypeScript; an earlier chain can still produce that receiver. The default async-return scope excludes rejection handlers and named callbacks. This is not the upstream return-await policy and no scheduling equivalence is promised.",
+    "The default async-return scope excludes direct loader callbacks passed to resolved `React.lazy` and `next/dynamic` imports because returning the module Promise is their framework contract.",
+    "All-promise-calls requires type information and excludes unproven/custom thenables, dynamic property names, property reads, destructuring, and extracted method aliases. Catch and finally remain available. Framework callback exclusions apply only to the default async-return scope."
   ],
   examples: [
     {
@@ -17687,15 +17688,28 @@ function promiseThenReceiver(node) {
   }
   return callee.object;
 }
+function directThenReceiver(node) {
+  const callee = node.callee;
+  if (callee.type !== import_utils103.AST_NODE_TYPES.MemberExpression) return null;
+  const property = callee.property;
+  const isThen = callee.computed ? property.type === import_utils103.AST_NODE_TYPES.Literal && property.value === "then" || property.type === import_utils103.AST_NODE_TYPES.TemplateLiteral && property.expressions.length === 0 && property.quasis[0]?.value.cooked === "then" : property.type === import_utils103.AST_NODE_TYPES.Identifier && property.name === "then";
+  return isThen ? callee.object : null;
+}
 function isProvenPromiseLike(node, services) {
   const checker = services.program.getTypeChecker();
   const tsNode = services.esTreeNodeToTSNodeMap.get(node);
-  const receiverType = checker.getTypeAtLocation(tsNode);
-  if ((receiverType.flags & (ts11.TypeFlags.Any | ts11.TypeFlags.Unknown | ts11.TypeFlags.Never)) !== 0) {
+  const receiverType = checker.getNonNullableType(checker.getTypeAtLocation(tsNode));
+  const members = receiverType.isUnion() ? receiverType.types : [receiverType];
+  return members.every((member) => isBuiltInPromiseType(member, services));
+}
+function isBuiltInPromiseType(type, services) {
+  if ((type.flags & (ts11.TypeFlags.Any | ts11.TypeFlags.Unknown | ts11.TypeFlags.Never)) !== 0) {
     return false;
   }
-  const thenSymbol = checker.getPropertyOfType(receiverType, "then");
-  const hasBuiltInPromiseDeclaration = thenSymbol?.declarations?.some(
+  const thenSymbol = services.program.getTypeChecker().getPropertyOfType(type, "then");
+  const declarations = thenSymbol?.declarations;
+  if (declarations === void 0 || declarations.length === 0) return false;
+  return declarations.every(
     (declaration) => {
       let owner = declaration.parent;
       while (owner !== void 0 && !ts11.isInterfaceDeclaration(owner)) {
@@ -17703,8 +17717,7 @@ function isProvenPromiseLike(node, services) {
       }
       return owner !== void 0 && (owner.name.text === "Promise" || owner.name.text === "PromiseLike") && services.program.isSourceFileDefaultLibrary(owner.getSourceFile());
     }
-  ) ?? false;
-  return hasBuiltInPromiseDeclaration;
+  );
 }
 var prefer_await_in_async_return_default = createRule({
   name: "prefer-await-in-async-return",
@@ -17712,15 +17725,20 @@ var prefer_await_in_async_return_default = createRule({
   meta: {
     type: "suggestion",
     docs: {
-      description: "Prefer explicit `await` when an async function directly returns one typed Promise `.then` transform."
+      description: "Prefer explicit `await` for proven Promise `.then` calls; the default scope checks direct async returns."
     },
-    schema: [],
+    schema: [{
+      type: "object",
+      properties: { scope: { type: "string", enum: ["async-return", "all-promise-calls"] } },
+      additionalProperties: false
+    }],
     messages: {
-      preferAwait: "This async function directly returns a Promise `.then` transform. Await the Promise, then return the transformed value with explicit async control flow."
+      preferAwait: "This async function directly returns a Promise `.then` transform. Await the Promise, then return the transformed value with explicit async control flow.",
+      preferAwaitCall: "This call uses built-in Promise.then(). Use async/await, preserving rejection handling and observable scheduling when rewriting."
     }
   },
-  defaultOptions: [],
-  create(context) {
+  defaultOptions: [{ scope: "async-return" }],
+  create(context, [options]) {
     let services;
     try {
       services = import_utils103.ESLintUtils.getParserServices(context);
@@ -17753,6 +17771,13 @@ var prefer_await_in_async_return_default = createRule({
         }
       },
       CallExpression(node) {
+        if (options.scope === "all-promise-calls") {
+          const receiver2 = directThenReceiver(node);
+          if (receiver2 !== null && isProvenPromiseLike(receiver2, services)) {
+            context.report({ node, messageId: "preferAwaitCall" });
+          }
+          return;
+        }
         const owner = directAsyncReturnOwner(node);
         if (owner === null || isFrameworkLoaderCallback(owner)) return;
         const receiver = promiseThenReceiver(node);
@@ -23808,7 +23833,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "16.2.4"
+  version: "16.2.5"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {

package/dist/index.d.cts

@@ -253,7 +253,9 @@ declare const RULES: {
     readonly "prefer-node-fs-promises": DocumentedRule<[], "preferAsyncFs">;
     readonly "prefer-non-nullable-collection": DocumentedRule<readonly [], "preferNonNullableCollection">;
     readonly "prefer-nullish-filter-predicate": DocumentedRule<readonly [], "preferNullishPredicate" | "replaceBoolean">;
-    readonly "prefer-await-in-async-return": DocumentedRule<readonly [], "preferAwait">;
+    readonly "prefer-await-in-async-return": DocumentedRule<readonly [{
+        readonly scope: "async-return" | "all-promise-calls";
+    }], "preferAwait" | "preferAwaitCall">;
     readonly "prefer-schema-for-api-payload": DocumentedRule<readonly [], "unparsedJsonAccess">;
     readonly "prefer-shared-zod-enum": DocumentedRule<[], "shareEnumDomain">;
     readonly "prefer-switch-for-repeated-equality": DocumentedRule<[], "preferSwitch">;
@@ -922,7 +924,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "16.2.4";
+        readonly version: "16.2.5";
     };
     readonly rules: {
         readonly "require-explicit-contract-implementation": DocumentedRule<readonly [], "declareActualContract">;
@@ -1052,7 +1054,9 @@ declare const PLUGIN: {
         readonly "prefer-node-fs-promises": DocumentedRule<[], "preferAsyncFs">;
         readonly "prefer-non-nullable-collection": DocumentedRule<readonly [], "preferNonNullableCollection">;
         readonly "prefer-nullish-filter-predicate": DocumentedRule<readonly [], "preferNullishPredicate" | "replaceBoolean">;
-        readonly "prefer-await-in-async-return": DocumentedRule<readonly [], "preferAwait">;
+        readonly "prefer-await-in-async-return": DocumentedRule<readonly [{
+            readonly scope: "async-return" | "all-promise-calls";
+        }], "preferAwait" | "preferAwaitCall">;
         readonly "prefer-schema-for-api-payload": DocumentedRule<readonly [], "unparsedJsonAccess">;
         readonly "prefer-shared-zod-enum": DocumentedRule<[], "shareEnumDomain">;
         readonly "prefer-switch-for-repeated-equality": DocumentedRule<[], "preferSwitch">;

package/dist/index.d.ts

@@ -253,7 +253,9 @@ declare const RULES: {
     readonly "prefer-node-fs-promises": DocumentedRule<[], "preferAsyncFs">;
     readonly "prefer-non-nullable-collection": DocumentedRule<readonly [], "preferNonNullableCollection">;
     readonly "prefer-nullish-filter-predicate": DocumentedRule<readonly [], "preferNullishPredicate" | "replaceBoolean">;
-    readonly "prefer-await-in-async-return": DocumentedRule<readonly [], "preferAwait">;
+    readonly "prefer-await-in-async-return": DocumentedRule<readonly [{
+        readonly scope: "async-return" | "all-promise-calls";
+    }], "preferAwait" | "preferAwaitCall">;
     readonly "prefer-schema-for-api-payload": DocumentedRule<readonly [], "unparsedJsonAccess">;
     readonly "prefer-shared-zod-enum": DocumentedRule<[], "shareEnumDomain">;
     readonly "prefer-switch-for-repeated-equality": DocumentedRule<[], "preferSwitch">;
@@ -922,7 +924,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "16.2.4";
+        readonly version: "16.2.5";
     };
     readonly rules: {
         readonly "require-explicit-contract-implementation": DocumentedRule<readonly [], "declareActualContract">;
@@ -1052,7 +1054,9 @@ declare const PLUGIN: {
         readonly "prefer-node-fs-promises": DocumentedRule<[], "preferAsyncFs">;
         readonly "prefer-non-nullable-collection": DocumentedRule<readonly [], "preferNonNullableCollection">;
         readonly "prefer-nullish-filter-predicate": DocumentedRule<readonly [], "preferNullishPredicate" | "replaceBoolean">;
-        readonly "prefer-await-in-async-return": DocumentedRule<readonly [], "preferAwait">;
+        readonly "prefer-await-in-async-return": DocumentedRule<readonly [{
+            readonly scope: "async-return" | "all-promise-calls";
+        }], "preferAwait" | "preferAwaitCall">;
         readonly "prefer-schema-for-api-payload": DocumentedRule<readonly [], "unparsedJsonAccess">;
         readonly "prefer-shared-zod-enum": DocumentedRule<[], "shareEnumDomain">;
         readonly "prefer-switch-for-repeated-equality": DocumentedRule<[], "preferSwitch">;

package/dist/index.js

@@ -17631,15 +17631,16 @@ import {
 } from "@typescript-eslint/utils";
 import * as ts11 from "typescript";
 var PREFER_AWAIT_IN_ASYNC_RETURN_DOCUMENTATION = {
-  summary: "Prefer explicit `await` when an async function directly returns one typed Promise `.then` transform.",
-  rationale: "Mixing a directly returned Promise callback into otherwise async control flow makes sequencing and failures harder to read.",
+  summary: "Prefer explicit `await` for proven Promise `.then` calls; the default scope checks direct async returns.",
+  rationale: "Promise callback chains mix explicit async control flow with nested callbacks, making sequencing and failure handling harder to read.",
   remediation: "Consider awaiting the Promise and returning the transformed value with ordinary async statements. Preserve catch boundaries, callback behavior, and observable scheduling when rewriting manually.",
   category: "maintainability",
   since: "15.6.3",
   limitations: [
-    "Only a single directly returned `.then` call with an inline callback is checked.",
-    "The receiver must be proven Promise-like by TypeScript; an earlier chain can still produce that receiver. Untyped receivers, rejection handlers and named callbacks are excluded. This is not the upstream return-await policy and no scheduling equivalence is promised.",
-    "Direct loader callbacks passed to resolved `React.lazy` and `next/dynamic` imports are excluded because returning the module Promise is their framework contract."
+    "The default async-return scope checks one directly returned `.then` call with an inline callback. The all-promise-calls scope checks direct calls to built-in Promise/PromiseLike.then, including optional and literal-computed calls, without automatic rewrites.",
+    "The receiver must be proven Promise-like by TypeScript; an earlier chain can still produce that receiver. The default async-return scope excludes rejection handlers and named callbacks. This is not the upstream return-await policy and no scheduling equivalence is promised.",
+    "The default async-return scope excludes direct loader callbacks passed to resolved `React.lazy` and `next/dynamic` imports because returning the module Promise is their framework contract.",
+    "All-promise-calls requires type information and excludes unproven/custom thenables, dynamic property names, property reads, destructuring, and extracted method aliases. Catch and finally remain available. Framework callback exclusions apply only to the default async-return scope."
   ],
   examples: [
     {
@@ -17696,15 +17697,28 @@ function promiseThenReceiver(node) {
   }
   return callee.object;
 }
+function directThenReceiver(node) {
+  const callee = node.callee;
+  if (callee.type !== AST_NODE_TYPES86.MemberExpression) return null;
+  const property = callee.property;
+  const isThen = callee.computed ? property.type === AST_NODE_TYPES86.Literal && property.value === "then" || property.type === AST_NODE_TYPES86.TemplateLiteral && property.expressions.length === 0 && property.quasis[0]?.value.cooked === "then" : property.type === AST_NODE_TYPES86.Identifier && property.name === "then";
+  return isThen ? callee.object : null;
+}
 function isProvenPromiseLike(node, services) {
   const checker = services.program.getTypeChecker();
   const tsNode = services.esTreeNodeToTSNodeMap.get(node);
-  const receiverType = checker.getTypeAtLocation(tsNode);
-  if ((receiverType.flags & (ts11.TypeFlags.Any | ts11.TypeFlags.Unknown | ts11.TypeFlags.Never)) !== 0) {
+  const receiverType = checker.getNonNullableType(checker.getTypeAtLocation(tsNode));
+  const members = receiverType.isUnion() ? receiverType.types : [receiverType];
+  return members.every((member) => isBuiltInPromiseType(member, services));
+}
+function isBuiltInPromiseType(type, services) {
+  if ((type.flags & (ts11.TypeFlags.Any | ts11.TypeFlags.Unknown | ts11.TypeFlags.Never)) !== 0) {
     return false;
   }
-  const thenSymbol = checker.getPropertyOfType(receiverType, "then");
-  const hasBuiltInPromiseDeclaration = thenSymbol?.declarations?.some(
+  const thenSymbol = services.program.getTypeChecker().getPropertyOfType(type, "then");
+  const declarations = thenSymbol?.declarations;
+  if (declarations === void 0 || declarations.length === 0) return false;
+  return declarations.every(
     (declaration) => {
       let owner = declaration.parent;
       while (owner !== void 0 && !ts11.isInterfaceDeclaration(owner)) {
@@ -17712,8 +17726,7 @@ function isProvenPromiseLike(node, services) {
       }
       return owner !== void 0 && (owner.name.text === "Promise" || owner.name.text === "PromiseLike") && services.program.isSourceFileDefaultLibrary(owner.getSourceFile());
     }
-  ) ?? false;
-  return hasBuiltInPromiseDeclaration;
+  );
 }
 var prefer_await_in_async_return_default = createRule({
   name: "prefer-await-in-async-return",
@@ -17721,15 +17734,20 @@ var prefer_await_in_async_return_default = createRule({
   meta: {
     type: "suggestion",
     docs: {
-      description: "Prefer explicit `await` when an async function directly returns one typed Promise `.then` transform."
+      description: "Prefer explicit `await` for proven Promise `.then` calls; the default scope checks direct async returns."
     },
-    schema: [],
+    schema: [{
+      type: "object",
+      properties: { scope: { type: "string", enum: ["async-return", "all-promise-calls"] } },
+      additionalProperties: false
+    }],
     messages: {
-      preferAwait: "This async function directly returns a Promise `.then` transform. Await the Promise, then return the transformed value with explicit async control flow."
+      preferAwait: "This async function directly returns a Promise `.then` transform. Await the Promise, then return the transformed value with explicit async control flow.",
+      preferAwaitCall: "This call uses built-in Promise.then(). Use async/await, preserving rejection handling and observable scheduling when rewriting."
     }
   },
-  defaultOptions: [],
-  create(context) {
+  defaultOptions: [{ scope: "async-return" }],
+  create(context, [options]) {
     let services;
     try {
       services = ESLintUtils13.getParserServices(context);
@@ -17762,6 +17780,13 @@ var prefer_await_in_async_return_default = createRule({
         }
       },
       CallExpression(node) {
+        if (options.scope === "all-promise-calls") {
+          const receiver2 = directThenReceiver(node);
+          if (receiver2 !== null && isProvenPromiseLike(receiver2, services)) {
+            context.report({ node, messageId: "preferAwaitCall" });
+          }
+          return;
+        }
         const owner = directAsyncReturnOwner(node);
         if (owner === null || isFrameworkLoaderCallback(owner)) return;
         const receiver = promiseThenReceiver(node);
@@ -23829,7 +23854,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "16.2.4"
+  version: "16.2.5"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/eslint-plugin",
-  "version": "16.2.4",
+  "version": "16.2.5",
   "packageManager": "npm@12.1.0",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",