eslint-plugin-reliability 3.1.7 → 3.1.8

package/src/rules/error-handling/no-unhandled-promise.js

@@ -1,20 +1,10 @@
 "use strict";
-/**
- * Copyright (c) 2025 Ofri Peretz
- * Licensed under the MIT License. Use of this source code is governed by the
- * MIT license that can be found in the LICENSE file.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noUnhandledPromise = void 0;
 exports.isLikelyPromiseExpression = isLikelyPromiseExpression;
 exports.isPromiseHandled = isPromiseHandled;
 const eslint_devkit_1 = require("@interlace/eslint-devkit");
 const eslint_devkit_2 = require("@interlace/eslint-devkit");
-/**
- * Built-in / library calls that are KNOWN to NOT return a promise. Firing
- * on these produces FPs (e.g., `setTimeout(...)`, `console.log(...)`,
- * `Math.floor(...)` are not unhandled promises).
- */
 const NEVER_RETURNS_PROMISE_FUNCTIONS = new Set([
     'setTimeout', 'clearTimeout', 'setInterval', 'clearInterval',
     'setImmediate', 'clearImmediate',
@@ -25,79 +15,45 @@ const NEVER_RETURNS_PROMISE_FUNCTIONS = new Set([
     'Array', 'Object',
 ]);
 const NEVER_RETURNS_PROMISE_METHODS = new Set([
-    // console / logger
     'log', 'error', 'warn', 'info', 'debug', 'trace', 'group', 'groupEnd',
     'time', 'timeEnd', 'assert',
-    // Math
     'floor', 'ceil', 'round', 'abs', 'min', 'max', 'pow', 'sqrt', 'random',
     'sin', 'cos', 'tan', 'log2', 'log10',
-    // String / Array helpers
     'slice', 'split', 'join', 'concat', 'includes', 'indexOf', 'lastIndexOf',
     'startsWith', 'endsWith', 'replace', 'replaceAll', 'trim', 'toLowerCase', 'toUpperCase',
     'repeat', 'padStart', 'padEnd', 'charAt', 'charCodeAt', 'codePointAt',
     'push', 'pop', 'shift', 'unshift', 'splice', 'reverse', 'sort',
     'map', 'filter', 'reduce', 'reduceRight', 'forEach', 'every', 'some', 'find', 'findIndex',
     'flat', 'flatMap', 'fill', 'copyWithin', 'entries', 'keys', 'values',
-    // JSON
     'parse', 'stringify',
-    // AbortController/AbortSignal
     'abort', 'addEventListener', 'removeEventListener', 'dispatchEvent',
-    // Date / Buffer / Number / Array static helpers (sync)
     'now', 'parse', 'UTC', 'from', 'of', 'isArray', 'isBuffer',
     'isInteger', 'isFinite', 'isNaN', 'isSafeInteger',
     'fromCharCode', 'fromCodePoint', 'raw',
-    // Object helpers (sync)
     'assign', 'freeze', 'isFrozen', 'create', 'defineProperty', 'defineProperties',
     'getOwnPropertyDescriptor', 'getOwnPropertyNames', 'getPrototypeOf', 'setPrototypeOf',
     'preventExtensions', 'isExtensible', 'seal', 'isSealed', 'fromEntries',
-    // Promise constructors that are themselves a promise but the callee is OK
 ]);
-/**
- * Globals whose methods are conventionally synchronous (no method on these
- * namespaces returns a Promise in the standard library). Used in addition
- * to `NEVER_RETURNS_PROMISE_METHODS` because matching by method name alone
- * is too coarse: `from` is sync on `Array`/`Buffer`/`Date` but could be
- * async on a user-defined object.
- */
 const SYNC_NAMESPACE_OBJECTS = new Set([
     'Math', 'JSON', 'Date', 'Buffer', 'Array', 'Object', 'Number', 'String',
     'Boolean', 'Symbol', 'BigInt', 'Reflect', 'console', 'process',
 ]);
-/**
- * Returns true if the call MIGHT return a Promise (default — we want to
- * preserve detection for unknown calls). Returns false only when the
- * callee is a known synchronous built-in (`setTimeout`, `console.log`,
- * `Math.floor`, etc.) — those structurally never return promises and
- * firing on them produces FPs. Keeping the default as "could be a
- * promise" preserves recall on user-defined async functions.
- *
- * Exported for direct Layer-2 unit testing: the non-CallExpression early
- * return is only reachable when called with a non-call node (kept for the
- * future `checkIdentifier` listener), which the current CallExpression-only
- * listener never produces.
- */
 function isLikelyPromiseExpression(node) {
     if (node.type !== 'CallExpression')
         return false;
     const callee = node.callee;
-    // Direct calls — skip known synchronous built-ins
     if (callee.type === 'Identifier') {
         const name = callee.name;
         if (NEVER_RETURNS_PROMISE_FUNCTIONS.has(name))
             return false;
         return true;
     }
-    // Method calls — skip known synchronous methods (Math.*, Array.*,
-    // String.*, console.*, JSON.*)
     if (callee.type === 'MemberExpression') {
         const prop = callee.property;
         if (prop.type === 'Identifier') {
             if (NEVER_RETURNS_PROMISE_METHODS.has(prop.name))
                 return false;
         }
-        // Static helpers on known sync namespaces — `Buffer.from`, `Date.now`,
-        // `Array.isArray`, `Object.keys`, etc. The standard library never
-        // returns a Promise from any method on these globals.
         const obj = callee.object;
         if (obj.type === 'Identifier' && SYNC_NAMESPACE_OBJECTS.has(obj.name)) {
             return false;
@@ -106,15 +62,6 @@ function isLikelyPromiseExpression(node) {
     }
     return true;
 }
-/**
- * Returns true when the call's parent indicates the promise is delegated
- * to a caller and therefore not "unhandled" at this site. This covers:
- *   - `return fn()` — the enclosing function returns the promise; its
- *     caller takes responsibility.
- *   - `() => fn()` — concise-body arrow returns the promise.
- *   - `.then(() => fn())` — already inside a promise chain (handled by
- *     `isInsidePromiseCallback`, but the arrow-body case is the same).
- */
 function isPromiseDelegatedToCaller(node) {
     const parent = node.parent;
     if (!parent)
@@ -125,9 +72,6 @@ function isPromiseDelegatedToCaller(node) {
         return true;
     return false;
 }
-/**
- * Check if a CallExpression is inside a promise chain callback
- */
 function isInsidePromiseCallback(node) {
     let current = node;
     let depth = 0;
@@ -137,10 +81,8 @@ function isInsidePromiseCallback(node) {
             .parent;
         if (!parent)
             break;
-        // Check if we're inside an arrow function or function expression
         if (parent.type === 'ArrowFunctionExpression' ||
             parent.type === 'FunctionExpression') {
-            // Check if this function is an argument to a promise method (.then, .catch, .finally)
             const funcParent = parent
                 .parent;
             if (funcParent &&
@@ -153,7 +95,6 @@ function isInsidePromiseCallback(node) {
                     if (methodName === 'then' ||
                         methodName === 'catch' ||
                         methodName === 'finally') {
-                        // We're inside a promise chain callback
                         return true;
                     }
                 }
@@ -164,16 +105,7 @@ function isInsidePromiseCallback(node) {
     }
     return false;
 }
-/**
- * Check if promise is handled (has .catch, .then, or is in try/catch)
- *
- * Exported for direct Layer-2 unit testing: the Identifier branch is only
- * reachable when called with an Identifier node (kept for the future
- * `checkIdentifier` listener), which the current CallExpression-only
- * listener never produces.
- */
 function isPromiseHandled(node) {
-    // For identifiers, check if they're used in a promise chain
     if (node.type === 'Identifier') {
         const parent = node.parent;
         if (parent &&
@@ -184,19 +116,16 @@ function isPromiseHandled(node) {
                 if (methodName === 'catch' ||
                     methodName === 'then' ||
                     methodName === 'finally') {
-                    // Check if this MemberExpression is used as a callee (called)
                     const memberParent = parent.parent;
                     if (memberParent &&
                         memberParent.type === 'CallExpression' &&
                         memberParent.callee === parent) {
-                        // Promise is handled by .then(), .catch(), or .finally()
                         return true;
                     }
                 }
             }
         }
     }
-    // For CallExpressions, traverse up the AST to find if this promise is part of a handled chain
     let current = node;
     let depth = 0;
     const maxDepth = 10;
@@ -205,29 +134,24 @@ function isPromiseHandled(node) {
             .parent;
         if (!parent)
             break;
-        // Check if parent is a MemberExpression with .catch/.then/.finally
         if (parent.type === 'MemberExpression' && parent.object === current) {
             if (parent.property.type === 'Identifier') {
                 const methodName = parent.property.name;
                 if (methodName === 'catch' ||
                     methodName === 'then' ||
                     methodName === 'finally') {
-                    // Check if this MemberExpression is used as a callee (called)
                     const memberParent = parent.parent;
                     if (memberParent &&
                         memberParent.type === 'CallExpression' &&
                         memberParent.callee === parent) {
-                        // Promise is handled by .then(), .catch(), or .finally()
                         return true;
                     }
                 }
             }
         }
-        // Check if in try/catch block
         if (parent.type === 'TryStatement') {
             return true;
         }
-        // Check if in await expression
         if (parent.type === 'AwaitExpression') {
             return true;
         }
@@ -314,55 +238,40 @@ exports.noUnhandledPromise = (0, eslint_devkit_2.createRule)({
         if (isTestFile) {
             return {};
         }
-        // const sourceCode = context.sourceCode; // Not used
-        /**
-         * Check call expressions for unhandled promises
-         */
         function checkCallExpression(node) {
-            // Skip CallExpressions that are inside promise chain callbacks
             if (isInsidePromiseCallback(node)) {
                 return;
             }
-            // `return fn()` / `() => fn()` — the promise is delegated to the
-            // caller. Flagging here would force `await` everywhere a promise
-            // is forwarded, which is wrong: forwarding IS handling.
             if (isPromiseDelegatedToCaller(node)) {
                 return;
             }
-            // Skip calls to promise methods (.then, .catch, .finally) as they are handled by definition
-            // But only if they have meaningful callbacks
             if (node.callee.type === 'MemberExpression' &&
                 node.callee.property.type === 'Identifier') {
                 const methodName = node.callee.property.name;
                 if (methodName === 'then' ||
                     methodName === 'catch' ||
                     methodName === 'finally') {
-                    // Check if the callback is empty or meaningless
                     if (node.arguments.length > 0 &&
                         node.arguments[0].type === 'ArrowFunctionExpression') {
                         const callback = node.arguments[0];
                         if (callback.body.type === 'BlockStatement' &&
                             callback.body.body.length === 0) {
-                            // Empty callback - don't skip, this should be flagged
                         }
                         else {
-                            return; // Has meaningful callback, skip
+                            return;
                         }
                     }
                     else {
-                        return; // Not an arrow function callback, assume it's handled
+                        return;
                     }
                 }
             }
-            // Check if it's a promise-returning function
             if (!isLikelyPromiseExpression(node)) {
                 return;
             }
-            // Check if it's already handled
             if (isPromiseHandled(node)) {
                 return;
             }
-            // Check if it's in a void expression
             if (ignoreVoidExpressions) {
                 const parent = node
                     .parent;
@@ -372,13 +281,9 @@ exports.noUnhandledPromise = (0, eslint_devkit_2.createRule)({
                     return;
                 }
             }
-            // Skip if this CallExpression is an argument to another CallExpression
-            // (e.g., console.log(fetch(url)) - we don't want to flag fetch(url) here)
             const parent = node
                 .parent;
             if (parent && parent.type === 'CallExpression') {
-                // Only skip if it's not part of a promise chain
-                // If it's the object of a MemberExpression with .then/.catch/.finally, it's a promise
                 const grandParent = parent.parent;
                 if (!(grandParent &&
                     grandParent.type === 'MemberExpression' &&
@@ -396,7 +301,7 @@ exports.noUnhandledPromise = (0, eslint_devkit_2.createRule)({
                 suggest: [
                     {
                         messageId: 'addCatch',
-                        fix: () => null, // Cannot auto-fix without context
+                        fix: () => null,
                     },
                     {
                         messageId: 'useTryCatch',
@@ -409,55 +314,6 @@ exports.noUnhandledPromise = (0, eslint_devkit_2.createRule)({
                 ],
             });
         }
-        /**
-         * Check identifier expressions for unhandled promises
-         * Note: Currently unused, keeping for future implementation
-         */
-        /*
-        function checkIdentifier(node: TSESTree.Identifier) {
-          // Skip identifiers that are inside promise chain callbacks
-          if (isInsidePromiseCallback({ type: 'CallExpression', callee: node, arguments: [], optional: false } as TSESTree.CallExpression)) {
-            return;
-          }
-    
-          // Check if it's a promise-like identifier
-          if (!isLikelyPromiseExpression(node)) {
-            return;
-          }
-    
-          // Check if it's already handled
-          if (isPromiseHandled(node)) {
-            return;
-          }
-    
-          // Check if it's in a void expression
-          if (ignoreVoidExpressions) {
-            const parent = (node as TSESTree.Node & { parent?: TSESTree.Node }).parent;
-            if (parent && parent.type === 'UnaryExpression' && parent.operator === 'void') {
-              return;
-            }
-          }
-    
-          context.report({
-            node,
-            messageId: 'unhandledPromise',
-            suggest: [
-              {
-                messageId: 'addCatch',
-                fix: () => null,
-              },
-              {
-                messageId: 'useTryCatch',
-                fix: () => null,
-              },
-              {
-                messageId: 'useAwait',
-                fix: () => null,
-              },
-            ],
-          });
-        }
-        */
         return {
             CallExpression: checkCallExpression,
         };

package/src/rules/reliability/no-await-in-loop.js

@@ -1,9 +1,4 @@
 "use strict";
-/**
- * Copyright (c) 2025 Ofri Peretz
- * Licensed under the MIT License. Use of this source code is governed by the
- * MIT license that can be found in the LICENSE file.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noAwaitInLoop = void 0;
 const eslint_devkit_1 = require("@interlace/eslint-devkit");
@@ -85,20 +80,16 @@ exports.noAwaitInLoop = (0, eslint_devkit_1.createRule)({
         const [options] = context.options;
         const { allowForOf = false, allowWhile = false } = options || {};
         function analyzeLoop(node, loopType) {
-            // Skip allowed loop types
             if ((loopType === 'ForOfStatement' && allowForOf) ||
                 (loopType === 'WhileStatement' && allowWhile)) {
                 return;
             }
-            // Find await expressions within the loop
             const awaitExpressions = [];
-            // Properties to skip to avoid circular references
             const skipProperties = new Set(['parent', 'tokens', 'comments', 'loc', 'range']);
             function findAwaits(currentNode) {
                 if (currentNode.type === 'AwaitExpression') {
                     awaitExpressions.push(currentNode);
                 }
-                // Don't traverse into nested functions (different scope)
                 if (currentNode.type !== 'FunctionDeclaration' &&
                     currentNode.type !== 'FunctionExpression' &&
                     currentNode.type !== 'ArrowFunctionExpression') {
@@ -121,7 +112,6 @@ exports.noAwaitInLoop = (0, eslint_devkit_1.createRule)({
             }
             findAwaits(node);
             if (awaitExpressions.length > 0) {
-                // Analyze the loop context to determine the best suggestion
                 const loopContext = analyzeLoopContext(node, loopType);
                 for (const awaitExpr of awaitExpressions) {
                     context.report({
@@ -148,9 +138,7 @@ exports.noAwaitInLoop = (0, eslint_devkit_1.createRule)({
                 operations: [],
                 node,
             };
-            // Properties to skip to avoid circular references
             const skipProps = new Set(['parent', 'tokens', 'comments', 'loc', 'range']);
-            // Analyze what operations are being performed in the loop
             function analyzeOperations(currentNode) {
                 if (currentNode.type === 'CallExpression') {
                     if (currentNode.callee.type === 'Identifier') {
@@ -161,23 +149,19 @@ exports.noAwaitInLoop = (0, eslint_devkit_1.createRule)({
                         loopCtx.operations.push(currentNode.callee.property.name);
                     }
                 }
-                // Check for dependencies between iterations
                 if (currentNode.type === 'AssignmentExpression' ||
                     currentNode.type === 'UpdateExpression') {
                     loopCtx.hasDependencies = true;
                 }
-                // Check for side effects that might require sequential execution
                 if (currentNode.type === 'CallExpression' &&
                     (loopCtx.operations.includes('push') ||
                         loopCtx.operations.includes('splice') ||
                         loopCtx.operations.includes('delete'))) {
                     loopCtx.hasSideEffects = true;
                 }
-                // Count operations
                 if (currentNode.type === 'AwaitExpression') {
                     loopCtx.operationCount++;
                 }
-                // Recursively analyze
                 for (const key in currentNode) {
                     if (skipProps.has(key))
                         continue;
@@ -195,7 +179,6 @@ exports.noAwaitInLoop = (0, eslint_devkit_1.createRule)({
                 }
             }
             analyzeOperations(node);
-            // Determine if operations can be concurrent
             if (loopCtx.hasDependencies || loopCtx.hasSideEffects) {
                 loopCtx.isSequential = true;
                 loopCtx.estimatedPerformance = `sequential (${loopCtx.operationCount} operations)`;
@@ -206,7 +189,6 @@ exports.noAwaitInLoop = (0, eslint_devkit_1.createRule)({
             }
             return loopCtx;
         }
-        // oxlint-disable-next-line consistent-function-scoping
         function getSuggestion(loopCtx) {
             if (loopCtx.isSequential) {
                 return 'operations may need to be sequential - consider if concurrency is safe';

package/src/rules/reliability/no-jsdoc-terminator-in-example.js

@@ -1,55 +1,32 @@
 "use strict";
-/**
- * Copyright (c) 2025 Ofri Peretz
- * Licensed under the MIT License. Use of this source code is governed by the
- * MIT license that can be found in the LICENSE file.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noJsdocTerminatorInExample = void 0;
 exports.findTerminatorsInExamples = findTerminatorsInExamples;
 const eslint_devkit_1 = require("@interlace/eslint-devkit");
-/**
- * Check whether a comment line is inside an @example block.
- * We track this by scanning line-by-line for @example / next-tag boundaries.
- *
- * Exported for direct Layer-2 unit testing: a real parser terminates the
- * enclosing block comment at the first star-slash sequence, so a comment
- * value containing one can never reach this function through a
- * normally-parsed file.
- */
 function findTerminatorsInExamples(commentText) {
     const lines = commentText.split('\n');
     let inExample = false;
     const offsets = [];
     let currentOffset = 0;
     for (const line of lines) {
-        // Strip leading whitespace and optional `*` prefix (block comment lines)
         const stripped = line.replace(/^\s*\*?\s?/, '');
-        // Detect @example start
         if (/^\s*@example\b/i.test(stripped)) {
             inExample = true;
-            currentOffset += line.length + 1; // +1 for the newline
+            currentOffset += line.length + 1;
             continue;
         }
-        // Detect any other JSDoc tag → exits @example scope
         if (/^\s*@\w+/.test(stripped) && !stripped.startsWith('@example')) {
             inExample = false;
             currentOffset += line.length + 1;
             continue;
         }
-        // If inside an example block, look for `*/` that isn't the closing
-        // terminator of the block comment itself (which is always at the very end)
         if (inExample) {
-            // Find `*/` occurrences within the original line content
             let searchStart = 0;
             while (searchStart < line.length) {
                 const idx = line.indexOf('*/', searchStart);
                 if (idx === -1)
                     break;
-                // The absolute offset within the full comment text
                 const absoluteOffset = currentOffset + idx;
-                // Don't flag the final `*/` that closes the entire comment —
-                // it always sits at the very end of the block comment.
                 const remaining = commentText.substring(absoluteOffset + 2).trim();
                 if (remaining.length > 0) {
                     offsets.push(absoluteOffset);
@@ -97,23 +74,18 @@ exports.noJsdocTerminatorInExample = (0, eslint_devkit_1.createRule)({
             Program() {
                 const comments = sourceCode.getAllComments();
                 for (const comment of comments) {
-                    // Only inspect block comments (JSDoc is always /* … */)
                     if (comment.type !== 'Block') {
                         continue;
                     }
                     const commentText = comment.value;
-                    // Quick bail-out: no @example or no `*/` inside → nothing to check
                     if (!/@example\b/i.test(commentText) ||
                         !commentText.includes('*/')) {
                         continue;
                     }
                     const offsets = findTerminatorsInExamples(commentText);
                     for (const offset of offsets) {
-                        // Calculate the absolute position in the source file.
-                        // comment.range[0] points to the opening `/*`, so the content
-                        // starts at range[0] + 2.
                         const absoluteStart = comment.range[0] + 2 + offset;
-                        const absoluteEnd = absoluteStart + 2; // length of `*/`
+                        const absoluteEnd = absoluteStart + 2;
                         context.report({
                             loc: {
                                 start: sourceCode.getLocFromIndex(absoluteStart),