eslint-plugin-use-disposables 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { ESLint, Linter } from 'eslint';
+declare const exported: ESLint.Plugin & {
+    configs: {
+        recommended: Linter.Config;
+    };
+};
+export default exported;

package/dist/index.js

@@ -0,0 +1,18 @@
+import useDisposables from './rules/use-disposables.js';
+// See eslint-plugin-imports-regulation's index.ts: ts-eslint's `RuleContext` carries ten members
+// ESLint's does not, and `create` compares its parameter in the opposite direction. The rule touches
+// only `sourceCode`, `options` and `report`, so the cast is carried here instead of by consumers.
+const rule = useDisposables;
+const plugin = {
+    meta: { name: 'eslint-plugin-use-disposables' },
+    rules: { 'use-disposables': rule },
+};
+const recommended = {
+    plugins: { 'use-disposables': plugin },
+    rules: { 'use-disposables/use-disposables': 'error' },
+};
+const exported = {
+    ...plugin,
+    configs: { recommended },
+};
+export default exported;

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

@@ -0,0 +1,11 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+type MessageIds = 'using' | 'awaitUsing' | 'suggestUsing' | 'suggestAwaitUsing';
+/**
+ * A disposable created into a plain variable, which nothing will ever dispose.
+ *
+ * Only values this code creates count — a call, a `new`, or an `await` of one. `const r = this.conn`
+ * 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, []>;
+export default rule;

package/dist/rules/use-disposables.js

@@ -0,0 +1,166 @@
+/**
+ * A disposable created into a plain variable, which nothing will ever dispose.
+ *
+ * Only values this code creates count — a call, a `new`, or an `await` of one. `const r = this.conn`
+ * 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.
+ */
+const rule = {
+    defaultOptions: [],
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Require a disposable held in a variable to be declared with `using`, or handed on',
+        },
+        schema: [],
+        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.',
+            suggestUsing: 'Declare it with `using`.',
+            suggestAwaitUsing: 'Declare it with `await using`.',
+        },
+    },
+    create(context) {
+        const services = context.sourceCode.parserServices;
+        // Type-aware only; see no-floating-promises for why this returns nothing rather than throwing.
+        if (!services?.program || !services.esTreeNodeToTSNodeMap)
+            return {};
+        const { esTreeNodeToTSNodeMap } = services;
+        const checker = services.program.getTypeChecker();
+        // 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];
+            const sync = parts.map(part => hasProperty(part, '__@dispose@'));
+            const async = parts.map(part => hasProperty(part, '__@asyncDispose@'));
+            if (sync.every(Boolean))
+                return 'sync';
+            if (parts.every((_, i) => sync[i] || async[i]))
+                return 'async';
+            return undefined;
+        };
+        const isStack = (node) => {
+            const name = checker.getTypeAtLocation(esTreeNodeToTSNodeMap.get(node)).getSymbol()?.getName();
+            return name === 'DisposableStack' || name === 'AsyncDisposableStack';
+        };
+        /** `stack.use(x)` and `stack.adopt(x)` hand back a value the stack already owns. */
+        const isStackHandOver = (node) => node.callee.type === 'MemberExpression'
+            && !node.callee.computed
+            && node.callee.property.type === 'Identifier'
+            && (node.callee.property.name === 'use' || node.callee.property.name === 'adopt')
+            && isStack(node.callee.object);
+        const isNullish = (node) => (node.type === 'Literal' && node.value === null)
+            || (node.type === 'Identifier' && node.name === 'undefined');
+        /** Whether the value is made here, rather than borrowed from somewhere that owns it. */
+        const creates = (node) => {
+            switch (node.type) {
+                case 'CallExpression': return !isStackHandOver(node);
+                case 'NewExpression': return true;
+                case 'AwaitExpression': return creates(node.argument);
+                case 'ChainExpression':
+                case 'TSAsExpression':
+                case 'TSNonNullExpression':
+                case 'TSSatisfiesExpression':
+                case 'TSTypeAssertion':
+                    return creates(node.expression);
+                case 'ConditionalExpression':
+                    return [node.consequent, node.alternate].every(branch => creates(branch) || isNullish(branch));
+                case 'LogicalExpression':
+                    return creates(node.left) && creates(node.right);
+                default: return false;
+            }
+        };
+        /** Whether this read of the variable passes the value on to something else. */
+        const handsOn = (node) => {
+            const parent = node.parent;
+            if (!parent)
+                return false;
+            switch (parent.type) {
+                case 'TSAsExpression':
+                case 'TSNonNullExpression':
+                case 'TSSatisfiesExpression':
+                case 'TSTypeAssertion':
+                case 'LogicalExpression':
+                    return handsOn(parent);
+                case 'ConditionalExpression': return parent.test !== node && handsOn(parent);
+                case 'SequenceExpression': return parent.expressions.at(-1) === node && handsOn(parent);
+                case 'ReturnStatement':
+                case 'YieldExpression':
+                case 'ArrayExpression':
+                case 'SpreadElement':
+                case 'JSXExpressionContainer':
+                case 'ExportSpecifier':
+                    return true;
+                case 'ArrowFunctionExpression': return parent.body === node;
+                case 'CallExpression':
+                case 'NewExpression':
+                    return parent.callee !== node;
+                case 'AssignmentExpression': return parent.right === node;
+                case 'VariableDeclarator': return parent.init === node;
+                case 'Property':
+                case 'PropertyDefinition':
+                    return parent.value === node;
+                default: return false;
+            }
+        };
+        const enclosingFunction = (node) => {
+            for (let at = node.parent; at; at = at.parent) {
+                if (at.type === 'FunctionDeclaration'
+                    || at.type === 'FunctionExpression'
+                    || at.type === 'ArrowFunctionExpression') {
+                    return at;
+                }
+            }
+            return undefined;
+        };
+        /** Whether swapping the keyword for `using` keeps the code compiling and meaning the same. */
+        const canSuggest = (declaration, declarator, variables, kind) => {
+            if (declaration.kind !== 'const' && declaration.kind !== 'let')
+                return false;
+            if (declaration.declarations.length !== 1 || declarator.id.type !== 'Identifier')
+                return false;
+            if (declaration.parent.type === 'SwitchCase')
+                return false;
+            if (variables.some(variable => variable.references.filter(ref => ref.isWrite()).length > 1))
+                return false;
+            // At the top of a module `await` is allowed, and these are type-aware ESM sources.
+            return kind === 'sync' || (enclosingFunction(declaration)?.async ?? true);
+        };
+        return {
+            VariableDeclaration(declaration) {
+                if (declaration.kind === 'using' || declaration.kind === 'await using')
+                    return;
+                if (declaration.parent.type === 'ExportNamedDeclaration')
+                    return;
+                for (const declarator of declaration.declarations) {
+                    const init = declarator.init;
+                    if (!init || !creates(init))
+                        continue;
+                    const kind = disposal(checker.getTypeAtLocation(esTreeNodeToTSNodeMap.get(init)));
+                    if (!kind)
+                        continue;
+                    const variables = context.sourceCode.getDeclaredVariables(declarator);
+                    const handedOn = variables.some(variable => variable.references.some(ref => ref.isRead() && handsOn(ref.identifier)));
+                    if (handedOn)
+                        continue;
+                    const keyword = context.sourceCode.getFirstToken(declaration);
+                    const replacement = kind === 'sync' ? 'using' : 'await using';
+                    context.report({
+                        node: declarator.id,
+                        messageId: kind === 'sync' ? 'using' : 'awaitUsing',
+                        suggest: keyword && canSuggest(declaration, declarator, variables, kind)
+                            ? [{
+                                    messageId: kind === 'sync' ? 'suggestUsing' : 'suggestAwaitUsing',
+                                    fix: fixer => fixer.replaceText(keyword, replacement),
+                                }]
+                            : [],
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "eslint-plugin-use-disposables",
+  "version": "0.1.0",
+  "description": "Require a disposable held in a variable to be declared with `using`, or handed on.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "typescript",
+    "using",
+    "disposable",
+    "explicit-resource-management"
+  ],
+  "license": "ISC",
+  "peerDependencies": {
+    "eslint": "^9.39.4 || ^10.0.0",
+    "typescript": ">=5.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "@typescript-eslint/utils": "^8.70.0",
+    "eslint": "^10.8.1",
+    "typescript-eslint": "^8.70.0"
+  },
+  "scripts": {
+    "compile": "tsc",
+    "build": "tsc --watch",
+    "test": "node --test --watch \"dist/**/*.test.js\"",
+    "test-once": "tsc && node --test \"dist/**/*.test.js\"",
+    "preview": "tsc && eslint --no-config-lookup -c preview.config.mjs fixtures",
+    "release": "node ../../scripts/release-package.ts"
+  }
+}