eslint-plugin-reliability 3.0.4 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-reliability",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "ESLint rules for runtime stability, fault tolerance, and type safety.",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -29,6 +29,9 @@ export declare const rules: {
     'no-await-in-loop': TSESLint.RuleModule<"awaitInLoop" | "suggestPromiseAll" | "suggestConcurrent" | "considerSequential" | "asyncLoopPattern", [(import("./rules/reliability/no-await-in-loop").Options | undefined)?], unknown, TSESLint.RuleListener> & {
         name: string;
     };
+    'no-jsdoc-terminator-in-example': TSESLint.RuleModule<"jsdocTerminatorInExample" | "wrapInQuotes", [(import("./rules/reliability/no-jsdoc-terminator-in-example").Options | undefined)?], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
     'error-handling/no-unhandled-promise': TSESLint.RuleModule<"unhandledPromise" | "addCatch" | "useTryCatch" | "useAwait", [(import("./rules/error-handling/no-unhandled-promise").Options | undefined)?], unknown, TSESLint.RuleListener> & {
         name: string;
     };
@@ -53,6 +56,9 @@ export declare const rules: {
     'reliability/no-await-in-loop': TSESLint.RuleModule<"awaitInLoop" | "suggestPromiseAll" | "suggestConcurrent" | "considerSequential" | "asyncLoopPattern", [(import("./rules/reliability/no-await-in-loop").Options | undefined)?], unknown, TSESLint.RuleListener> & {
         name: string;
     };
+    'reliability/no-jsdoc-terminator-in-example': TSESLint.RuleModule<"jsdocTerminatorInExample" | "wrapInQuotes", [(import("./rules/reliability/no-jsdoc-terminator-in-example").Options | undefined)?], unknown, TSESLint.RuleListener> & {
+        name: string;
+    };
 };
 export declare const plugin: {
     meta: {
@@ -84,6 +90,9 @@ export declare const plugin: {
         'no-await-in-loop': TSESLint.RuleModule<"awaitInLoop" | "suggestPromiseAll" | "suggestConcurrent" | "considerSequential" | "asyncLoopPattern", [(import("./rules/reliability/no-await-in-loop").Options | undefined)?], unknown, TSESLint.RuleListener> & {
             name: string;
         };
+        'no-jsdoc-terminator-in-example': TSESLint.RuleModule<"jsdocTerminatorInExample" | "wrapInQuotes", [(import("./rules/reliability/no-jsdoc-terminator-in-example").Options | undefined)?], unknown, TSESLint.RuleListener> & {
+            name: string;
+        };
         'error-handling/no-unhandled-promise': TSESLint.RuleModule<"unhandledPromise" | "addCatch" | "useTryCatch" | "useAwait", [(import("./rules/error-handling/no-unhandled-promise").Options | undefined)?], unknown, TSESLint.RuleListener> & {
             name: string;
         };
@@ -108,12 +117,15 @@ export declare const plugin: {
         'reliability/no-await-in-loop': TSESLint.RuleModule<"awaitInLoop" | "suggestPromiseAll" | "suggestConcurrent" | "considerSequential" | "asyncLoopPattern", [(import("./rules/reliability/no-await-in-loop").Options | undefined)?], unknown, TSESLint.RuleListener> & {
             name: string;
         };
+        'reliability/no-jsdoc-terminator-in-example': TSESLint.RuleModule<"jsdocTerminatorInExample" | "wrapInQuotes", [(import("./rules/reliability/no-jsdoc-terminator-in-example").Options | undefined)?], unknown, TSESLint.RuleListener> & {
+            name: string;
+        };
     };
 };
 export declare const configs: {
     recommended: {
         plugins: {
-            '@interlace/reliability': {
+            reliability: {
                 meta: {
                     name: string;
                     version: string;
@@ -143,6 +155,9 @@ export declare const configs: {
                     'no-await-in-loop': TSESLint.RuleModule<"awaitInLoop" | "suggestPromiseAll" | "suggestConcurrent" | "considerSequential" | "asyncLoopPattern", [(import("./rules/reliability/no-await-in-loop").Options | undefined)?], unknown, TSESLint.RuleListener> & {
                         name: string;
                     };
+                    'no-jsdoc-terminator-in-example': TSESLint.RuleModule<"jsdocTerminatorInExample" | "wrapInQuotes", [(import("./rules/reliability/no-jsdoc-terminator-in-example").Options | undefined)?], unknown, TSESLint.RuleListener> & {
+                        name: string;
+                    };
                     'error-handling/no-unhandled-promise': TSESLint.RuleModule<"unhandledPromise" | "addCatch" | "useTryCatch" | "useAwait", [(import("./rules/error-handling/no-unhandled-promise").Options | undefined)?], unknown, TSESLint.RuleListener> & {
                         name: string;
                     };
@@ -167,13 +182,16 @@ export declare const configs: {
                     'reliability/no-await-in-loop': TSESLint.RuleModule<"awaitInLoop" | "suggestPromiseAll" | "suggestConcurrent" | "considerSequential" | "asyncLoopPattern", [(import("./rules/reliability/no-await-in-loop").Options | undefined)?], unknown, TSESLint.RuleListener> & {
                         name: string;
                     };
+                    'reliability/no-jsdoc-terminator-in-example': TSESLint.RuleModule<"jsdocTerminatorInExample" | "wrapInQuotes", [(import("./rules/reliability/no-jsdoc-terminator-in-example").Options | undefined)?], unknown, TSESLint.RuleListener> & {
+                        name: string;
+                    };
                 };
             };
         };
         rules: {
-            '@interlace/reliability/error-handling/no-silent-errors': "warn";
-            '@interlace/reliability/reliability/no-missing-null-checks': "warn";
-            '@interlace/reliability/reliability/require-network-timeout': "error";
+            'reliability/no-silent-errors': "warn";
+            'reliability/no-missing-null-checks': "warn";
+            'reliability/require-network-timeout': "error";
         };
     };
 };

package/src/index.js

@@ -16,6 +16,7 @@ const no_missing_null_checks_1 = require("./rules/reliability/no-missing-null-ch
 const no_unsafe_type_narrowing_1 = require("./rules/reliability/no-unsafe-type-narrowing");
 const require_network_timeout_1 = require("./rules/reliability/require-network-timeout");
 const no_await_in_loop_1 = require("./rules/reliability/no-await-in-loop");
+const no_jsdoc_terminator_in_example_1 = require("./rules/reliability/no-jsdoc-terminator-in-example");
 exports.rules = {
     'no-unhandled-promise': no_unhandled_promise_1.noUnhandledPromise,
     'no-silent-errors': no_silent_errors_1.noSilentErrors,
@@ -25,6 +26,7 @@ exports.rules = {
     'no-unsafe-type-narrowing': no_unsafe_type_narrowing_1.noUnsafeTypeNarrowing,
     'require-network-timeout': require_network_timeout_1.requireNetworkTimeout,
     'no-await-in-loop': no_await_in_loop_1.noAwaitInLoop,
+    'no-jsdoc-terminator-in-example': no_jsdoc_terminator_in_example_1.noJsdocTerminatorInExample,
     // Categorized names
     'error-handling/no-unhandled-promise': no_unhandled_promise_1.noUnhandledPromise,
     'error-handling/no-silent-errors': no_silent_errors_1.noSilentErrors,
@@ -34,6 +36,7 @@ exports.rules = {
     'reliability/no-unsafe-type-narrowing': no_unsafe_type_narrowing_1.noUnsafeTypeNarrowing,
     'reliability/require-network-timeout': require_network_timeout_1.requireNetworkTimeout,
     'reliability/no-await-in-loop': no_await_in_loop_1.noAwaitInLoop,
+    'reliability/no-jsdoc-terminator-in-example': no_jsdoc_terminator_in_example_1.noJsdocTerminatorInExample,
 };
 exports.plugin = {
     meta: {
@@ -45,12 +48,12 @@ exports.plugin = {
 exports.configs = {
     recommended: {
         plugins: {
-            '@interlace/reliability': exports.plugin,
+            reliability: exports.plugin,
         },
         rules: {
-            '@interlace/reliability/error-handling/no-silent-errors': 'warn',
-            '@interlace/reliability/reliability/no-missing-null-checks': 'warn',
-            '@interlace/reliability/reliability/require-network-timeout': 'error',
+            'reliability/no-silent-errors': 'warn',
+            'reliability/no-missing-null-checks': 'warn',
+            'reliability/require-network-timeout': 'error',
         },
     },
 };

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

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+/**
+ * ESLint Rule: no-jsdoc-terminator-in-example
+ * Detects `* /` sequences inside JSDoc @example blocks that can
+ * prematurely close the comment and cause TypeScript compilation errors.
+ *
+ * Inspired by real DefinitelyTyped CI failures where patterns like
+ * `*\/*` (MIME types, glob patterns) inside @example terminated the
+ * JSDoc block early, producing broken type definitions.
+ *
+ * @see https://github.com/microsoft/dtslint
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type MessageIds = 'jsdocTerminatorInExample' | 'wrapInQuotes';
+export interface Options {
+}
+type RuleOptions = [Options?];
+export declare const noJsdocTerminatorInExample: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};

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

@@ -0,0 +1,131 @@
+"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;
+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.
+ */
+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
+            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);
+                }
+                searchStart = idx + 2;
+            }
+        }
+        currentOffset += line.length + 1;
+    }
+    return offsets;
+}
+exports.noJsdocTerminatorInExample = (0, eslint_devkit_1.createRule)({
+    name: 'no-jsdoc-terminator-in-example',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Detects `*/` sequences inside JSDoc @example blocks that prematurely close the comment',
+        },
+        fixable: 'code',
+        hasSuggestions: true,
+        messages: {
+            jsdocTerminatorInExample: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.WARNING,
+                issueName: 'JSDoc Terminator in @example',
+                description: 'The `*/` sequence inside an @example block will prematurely close the JSDoc comment, causing compilation errors. Wrap the pattern in quotes or use an alternative representation.',
+                severity: 'HIGH',
+                fix: "Wrap the pattern containing `*/` in quotes, e.g. `'*/*'` instead of `*/*`",
+                documentationLink: 'https://jsdoc.app/tags-example',
+            }),
+            wrapInQuotes: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Wrap Pattern in Quotes',
+                description: "Wrap the `*/` pattern in single quotes to prevent premature JSDoc termination",
+                severity: 'LOW',
+                fix: "Replace `*/` with `'*/'` (single-quoted) inside the @example block",
+                documentationLink: 'https://jsdoc.app/tags-example',
+            }),
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const sourceCode = context.sourceCode || context.sourceCode;
+        return {
+            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 `*/`
+                        context.report({
+                            loc: {
+                                start: sourceCode.getLocFromIndex(absoluteStart),
+                                end: sourceCode.getLocFromIndex(absoluteEnd),
+                            },
+                            messageId: 'jsdocTerminatorInExample',
+                            suggest: [
+                                {
+                                    messageId: 'wrapInQuotes',
+                                    fix: (fixer) => {
+                                        return fixer.replaceTextRange([absoluteStart, absoluteEnd], "'*/'");
+                                    },
+                                },
+                            ],
+                        });
+                    }
+                }
+            },
+        };
+    },
+});