eslint-plugin-use-disposables 0.1.0 → 0.1.1

package/dist/rules/use-disposables.d.ts

@@ -1,5 +1,16 @@
 import type { TSESLint } from '@typescript-eslint/utils';
 type MessageIds = 'using' | 'awaitUsing' | 'suggestUsing' | 'suggestAwaitUsing';
+/** A type name, matching any declaration of it, or one declared in a package's own files. */
+type Exception = string | {
+    name: string;
+    package: string;
+};
+type Options = [
+    {
+        defaultExceptions?: Exception[];
+        customExceptions?: Exception[];
+    }?
+];
 /**
  * A disposable created into a plain variable, which nothing will ever dispose.
  *
@@ -7,5 +18,5 @@ type MessageIds = 'using' | 'awaitUsing' | 'suggestUsing' | 'suggestAwaitUsing';
  * borrows a resource someone else owns, and `using` there would dispose it out from under them.
  * A variable that is returned, passed, yielded, stored or exported has handed ownership on.
  */
-declare const rule: TSESLint.RuleModule<MessageIds, []>;
+declare const rule: TSESLint.RuleModule<MessageIds, Options>;
 export default rule;

package/dist/rules/use-disposables.js

@@ -1,3 +1,36 @@
+/**
+ * Node types where "never disposed" is the normal case: the work finishes or is cancelled by itself,
+ * and `using` would kill the child, abort the stream or cancel the timer. `net.Server` and
+ * `dgram.Socket` are left out on purpose — one left listening is the leak this rule is for.
+ */
+const nodeExceptions = [
+    'ChildProcess',
+    'Worker',
+    'Timeout',
+    'Immediate',
+    'Readable',
+    'Writable',
+    'Utf8Stream',
+    'Interface',
+    'CPUProfileHandle',
+    'SyncCPUProfileHandle',
+    'HeapProfileHandle',
+    'GCProfiler',
+].map(name => ({ name, package: '@types/node' }));
+const exceptionSchema = {
+    type: 'array',
+    items: {
+        oneOf: [
+            { type: 'string' },
+            {
+                type: 'object',
+                properties: { name: { type: 'string' }, package: { type: 'string' } },
+                required: ['name', 'package'],
+                additionalProperties: false,
+            },
+        ],
+    },
+};
 /**
  * A disposable created into a plain variable, which nothing will ever dispose.
  *
@@ -6,17 +39,23 @@
  * A variable that is returned, passed, yielded, stored or exported has handed ownership on.
  */
 const rule = {
-    defaultOptions: [],
+    defaultOptions: [{ defaultExceptions: nodeExceptions, customExceptions: [] }],
     meta: {
         type: 'problem',
         hasSuggestions: true,
         docs: {
             description: 'Require a disposable held in a variable to be declared with `using`, or handed on',
         },
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: { defaultExceptions: exceptionSchema, customExceptions: exceptionSchema },
+                additionalProperties: false,
+            },
+        ],
         messages: {
-            using: 'Disposable is never disposed: declare it with `using`, or return or pass it on.',
-            awaitUsing: 'Disposable is never disposed: declare it with `await using`, or return or pass it on.',
+            using: 'Disposable assigned to a `{{kind}}` variable. Use `using` instead.',
+            awaitUsing: 'Disposable assigned to a `{{kind}}` variable. Use `await using` instead.',
             suggestUsing: 'Declare it with `using`.',
             suggestAwaitUsing: 'Declare it with `await using`.',
         },
@@ -28,12 +67,37 @@ const rule = {
             return {};
         const { esTreeNodeToTSNodeMap } = services;
         const checker = services.program.getTypeChecker();
+        const options = context.options[0];
+        const exceptions = [
+            ...options?.defaultExceptions ?? nodeExceptions,
+            ...options?.customExceptions ?? [],
+        ];
+        const declaredIn = (symbol, pkg) => (symbol.getDeclarations() ?? [])
+            .some(declaration => declaration.getSourceFile().fileName.includes(`/node_modules/${pkg}/`));
+        const matches = (symbol) => exceptions.some(exception => typeof exception === 'string'
+            ? symbol.getName() === exception
+            : symbol.getName() === exception.name && declaredIn(symbol, exception.package));
+        /** Whether the type, or any class or interface it extends, is an exception. */
+        const isExcepted = (type, seen = new Set()) => {
+            const symbol = type.getSymbol();
+            if (!symbol || seen.has(symbol))
+                return false;
+            seen.add(symbol);
+            if (matches(symbol))
+                return true;
+            const declared = checker.getDeclaredTypeOfSymbol(symbol);
+            if (!declared.isClassOrInterface())
+                return false;
+            return (checker.getBaseTypes(declared) ?? []).some(base => isExcepted(base, seen));
+        };
         // TypeScript keys `[Symbol.dispose]` as `__@dispose@<id>`.
         const hasProperty = (type, prefix) => type.getProperties().some(property => String(property.escapedName).startsWith(prefix));
         /** How the value can be disposed, when every branch that is not nullish can be. */
         const disposal = (type) => {
             const present = checker.getNonNullableType(type);
             const parts = present.isUnion() ? present.types : [present];
+            if (parts.some(part => isExcepted(part)))
+                return undefined;
             const sync = parts.map(part => hasProperty(part, '__@dispose@'));
             const async = parts.map(part => hasProperty(part, '__@asyncDispose@'));
             if (sync.every(Boolean))
@@ -151,6 +215,7 @@ const rule = {
                     context.report({
                         node: declarator.id,
                         messageId: kind === 'sync' ? 'using' : 'awaitUsing',
+                        data: { kind: declaration.kind },
                         suggest: keyword && canSuggest(declaration, declarator, variables, kind)
                             ? [{
                                     messageId: kind === 'sync' ? 'suggestUsing' : 'suggestAwaitUsing',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-use-disposables",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Require a disposable held in a variable to be declared with `using`, or handed on.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "typescript": ">=5.2"
   },
   "devDependencies": {
-    "@types/node": "^22.19.15",
+    "@types/node": "^24.19.1",
     "@typescript-eslint/utils": "^8.70.0",
     "eslint": "^10.8.1",
     "typescript-eslint": "^8.70.0"