@antithrow/eslint-plugin 1.0.0 → 1.1.0

package/README.md

@@ -24,8 +24,8 @@ Add the recommended config to your `eslint.config.ts`:
 import antithrow from "@antithrow/eslint-plugin";
 
 export default [
-	// ... your other configs
-	antithrow.configs.recommended,
+  // ... your other configs
+  antithrow.configs.recommended,
 ];
 ```
 
@@ -35,14 +35,15 @@ Or configure rules individually:
 import antithrow from "@antithrow/eslint-plugin";
 
 export default [
-	{
-		plugins: {
-			"@antithrow": antithrow,
-		},
-		rules: {
-			"@antithrow/no-unused-result": "error",
-		},
-	},
+  {
+    plugins: {
+      "@antithrow": antithrow,
+    },
+    rules: {
+      "@antithrow/no-unsafe-unwrap": "warn",
+      "@antithrow/no-unused-result": "error",
+    },
+  },
 ];
 ```
 
@@ -50,4 +51,5 @@ export default [
 
 | Rule | Description | Recommended |
 | --- | --- | --- |
+| [`no-unsafe-unwrap`](./docs/rules/no-unsafe-unwrap.md) | Disallow `unwrap`/`expect` APIs on antithrow `Result` values | `warn` |
 | [`no-unused-result`](./docs/rules/no-unused-result.md) | Require `Result` and `ResultAsync` values to be used | `error` |

package/dist/index.js

@@ -1,11 +1,12 @@
 import packageJson from "../package.json" with { type: "json" };
-import { noUnusedResult } from "./rules/index.js";
+import { noUnsafeUnwrap, noUnusedResult } from "./rules/index.js";
 const plugin = {
     meta: {
         name: packageJson.name,
         version: packageJson.version,
     },
     rules: {
+        "no-unsafe-unwrap": noUnsafeUnwrap,
         "no-unused-result": noUnusedResult,
     },
     configs: {},
@@ -17,6 +18,7 @@ plugin.configs = {
             "@antithrow": plugin,
         },
         rules: {
+            "@antithrow/no-unsafe-unwrap": "warn",
             "@antithrow/no-unused-result": "error",
         },
     },

package/dist/rules/index.d.ts

@@ -1 +1,2 @@
+export { noUnsafeUnwrap } from "./no-unsafe-unwrap.js";
 export { noUnusedResult } from "./no-unused-result.js";

package/dist/rules/index.js

@@ -1 +1,2 @@
+export { noUnsafeUnwrap } from "./no-unsafe-unwrap.js";
 export { noUnusedResult } from "./no-unused-result.js";

package/dist/rules/no-unsafe-unwrap.d.ts

@@ -0,0 +1,11 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+/** @lintignore */
+export declare const MessageId: {
+    readonly UNSAFE_UNWRAP: "unsafeUnwrap";
+    readonly UNWRAP_OK_VALUE: "unwrapOkValue";
+    readonly UNWRAP_ERR_ERROR: "unwrapErrError";
+};
+export type MessageId = (typeof MessageId)[keyof typeof MessageId];
+export declare const noUnsafeUnwrap: ESLintUtils.RuleModule<MessageId, [], import("../create-rule.js").AntithrowPluginDocs, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/no-unsafe-unwrap.js

@@ -0,0 +1,182 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+import { createRule } from "../create-rule.js";
+import { getResultVariant, isResultType, ResultVariant } from "./utils/result-type.js";
+/** @lintignore */
+export const MessageId = {
+    UNSAFE_UNWRAP: "unsafeUnwrap",
+    UNWRAP_OK_VALUE: "unwrapOkValue",
+    UNWRAP_ERR_ERROR: "unwrapErrError",
+};
+const BANNED_METHOD_NAMES = new Set(["unwrap", "unwrapErr", "expect", "expectErr"]);
+const FIXABLE_OK_METHOD_NAMES = new Set(["unwrap"]);
+const FIXABLE_ERR_METHOD_NAMES = new Set(["unwrapErr"]);
+/**
+ * Extracts the property name from a `MemberExpression` when it can be
+ * statically determined. Handles `obj.prop`, `obj["prop"]`, and
+ * `` obj[`prop`] `` (template literals with no interpolations).
+ * Returns `null` for dynamic access like `obj[variable]`.
+ */
+function getStaticMemberName(node) {
+    if (!node.computed && node.property.type === "Identifier") {
+        return node.property.name;
+    }
+    if (node.computed &&
+        node.property.type === "Literal" &&
+        typeof node.property.value === "string") {
+        return node.property.value;
+    }
+    if (node.computed &&
+        node.property.type === "TemplateLiteral" &&
+        node.property.expressions.length === 0) {
+        const [quasi] = node.property.quasis;
+        return quasi?.value.cooked ?? null;
+    }
+    return null;
+}
+/**
+ * Like {@link getStaticMemberName} but for destructuring patterns.
+ * Extracts the key name from `{ key: value }` in an `ObjectPattern`.
+ * Handles identifier keys, string literal keys, and static template
+ * literal keys. Returns `null` for computed keys with dynamic expressions.
+ */
+function getDestructuredPropertyName(node) {
+    if (node.computed) {
+        if (node.key.type === "Literal" && typeof node.key.value === "string") {
+            return node.key.value;
+        }
+        if (node.key.type === "TemplateLiteral" && node.key.expressions.length === 0) {
+            const [quasi] = node.key.quasis;
+            return quasi?.value.cooked ?? null;
+        }
+        return null;
+    }
+    if (node.key.type === "Identifier") {
+        return node.key.name;
+    }
+    if (node.key.type === "Literal" && typeof node.key.value === "string") {
+        return node.key.value;
+    }
+    return null;
+}
+function getCallExpression(node) {
+    if (node.parent.type === "CallExpression" && node.parent.callee === node) {
+        return node.parent;
+    }
+    return null;
+}
+function getFixedMemberExpressionText(node, method, propertyName, sourceCode) {
+    const memberText = sourceCode.getText(node);
+    const propertyText = sourceCode.getText(node.property);
+    const oldSuffix = node.computed
+        ? `${node.optional ? "?.[" : "["}${propertyText}]`
+        : `${node.optional ? "?." : "."}${method}`;
+    if (!memberText.endsWith(oldSuffix)) {
+        return null;
+    }
+    const baseText = memberText.slice(0, memberText.length - oldSuffix.length);
+    return `${baseText}${node.optional ? "?." : "."}${propertyName}`;
+}
+export const noUnsafeUnwrap = createRule({
+    name: "no-unsafe-unwrap",
+    meta: {
+        type: "problem",
+        fixable: "code",
+        docs: {
+            description: "Disallow unsafe unwrap APIs on Result and ResultAsync values to prevent unexpected throws.",
+            recommended: true,
+            requiresTypeChecking: true,
+        },
+        messages: {
+            [MessageId.UNSAFE_UNWRAP]: "Avoid `{{ method }}` on Result values. Handle both branches explicitly instead.",
+            [MessageId.UNWRAP_OK_VALUE]: "`{{ method }}` on `Ok` is unnecessary. Use `.value` instead.",
+            [MessageId.UNWRAP_ERR_ERROR]: "`{{ method }}` on `Err` is unnecessary. Use `.error` instead.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const services = ESLintUtils.getParserServices(context);
+        const checker = services.program.getTypeChecker();
+        return {
+            MemberExpression(node) {
+                const method = getStaticMemberName(node);
+                if (!method || !BANNED_METHOD_NAMES.has(method)) {
+                    return;
+                }
+                const tsNode = services.esTreeNodeToTSNodeMap.get(node.object);
+                const type = checker.getTypeAtLocation(tsNode);
+                if (!isResultType(type)) {
+                    return;
+                }
+                const callExpression = getCallExpression(node);
+                const variant = getResultVariant(type);
+                if (callExpression && variant === ResultVariant.OK && FIXABLE_OK_METHOD_NAMES.has(method)) {
+                    context.report({
+                        node,
+                        messageId: MessageId.UNWRAP_OK_VALUE,
+                        data: { method },
+                        fix(fixer) {
+                            const fixedText = getFixedMemberExpressionText(node, method, "value", context.sourceCode);
+                            if (!fixedText) {
+                                return null;
+                            }
+                            return fixer.replaceText(callExpression, fixedText);
+                        },
+                    });
+                    return;
+                }
+                if (callExpression &&
+                    variant === ResultVariant.ERR &&
+                    FIXABLE_ERR_METHOD_NAMES.has(method)) {
+                    context.report({
+                        node,
+                        messageId: MessageId.UNWRAP_ERR_ERROR,
+                        data: { method },
+                        fix(fixer) {
+                            const fixedText = getFixedMemberExpressionText(node, method, "error", context.sourceCode);
+                            if (!fixedText) {
+                                return null;
+                            }
+                            return fixer.replaceText(callExpression, fixedText);
+                        },
+                    });
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: MessageId.UNSAFE_UNWRAP,
+                    data: { method },
+                });
+            },
+            Property(node) {
+                if (node.parent.type !== "ObjectPattern") {
+                    return;
+                }
+                const method = getDestructuredPropertyName(node);
+                if (!method || !BANNED_METHOD_NAMES.has(method)) {
+                    return;
+                }
+                // Resolve the node whose type represents the value being destructured.
+                // For most contexts (variable declarations, function parameters, for-of
+                // loops), the ObjectPattern itself carries the correct type. However, in
+                // assignment destructuring (`({ unwrap } = result)`), the pattern's type
+                // reflects the target bindings, not the source, so we use the RHS instead.
+                const pattern = node.parent;
+                let typeSourceNode = pattern;
+                if (pattern.parent.type === "AssignmentExpression" && pattern.parent.left === pattern) {
+                    typeSourceNode = pattern.parent.right;
+                }
+                const tsNode = services.esTreeNodeToTSNodeMap.get(typeSourceNode);
+                const type = checker.getTypeAtLocation(tsNode);
+                if (!isResultType(type)) {
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: MessageId.UNSAFE_UNWRAP,
+                    data: { method },
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-unused-result.d.ts

@@ -1,4 +1,10 @@
 import { ESLintUtils } from "@typescript-eslint/utils";
-export declare const noUnusedResult: ESLintUtils.RuleModule<"unusedResult", [], import("../create-rule.js").AntithrowPluginDocs, ESLintUtils.RuleListener> & {
+/** @lintignore */
+export declare const MessageId: {
+    readonly UNUSED_RESULT: "unusedResult";
+    readonly ADD_VOID: "addVoid";
+};
+export type MessageId = (typeof MessageId)[keyof typeof MessageId];
+export declare const noUnusedResult: ESLintUtils.RuleModule<MessageId, [], import("../create-rule.js").AntithrowPluginDocs, ESLintUtils.RuleListener> & {
     name: string;
 };

package/dist/rules/no-unused-result.js

@@ -1,36 +1,38 @@
 import { ESLintUtils } from "@typescript-eslint/utils";
-import ts from "typescript";
 import { createRule } from "../create-rule.js";
-const RESULT_TYPE_NAMES = new Set(["Ok", "Err", "ResultAsync"]);
-function isResultType(type) {
-    if (type.isUnion()) {
-        return type.types.some((t) => isResultType(t));
+import { isResultType } from "./utils/result-type.js";
+function needsParentheses(node) {
+    switch (node.type) {
+        case "SequenceExpression":
+        case "AssignmentExpression":
+        case "ConditionalExpression":
+        case "LogicalExpression":
+        case "BinaryExpression":
+        case "TSAsExpression":
+        case "TSSatisfiesExpression":
+            return true;
+        default:
+            return false;
     }
-    const flags = type.getFlags();
-    if (flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) {
-        return false;
-    }
-    const symbol = type.getSymbol();
-    if (!symbol || !RESULT_TYPE_NAMES.has(symbol.getName())) {
-        return false;
-    }
-    const declarations = symbol.getDeclarations() ?? [];
-    return declarations.some((decl) => {
-        const sourceFile = decl.getSourceFile();
-        return sourceFile.fileName.includes("antithrow");
-    });
 }
+/** @lintignore */
+export const MessageId = {
+    UNUSED_RESULT: "unusedResult",
+    ADD_VOID: "addVoid",
+};
 export const noUnusedResult = createRule({
     name: "no-unused-result",
     meta: {
         type: "problem",
+        hasSuggestions: true,
         docs: {
             description: "Require Result and ResultAsync values to be used, preventing silently ignored errors.",
             recommended: true,
             requiresTypeChecking: true,
         },
         messages: {
-            unusedResult: "This Result must be used. Handle the error case or explicitly discard it with `void`.",
+            [MessageId.UNUSED_RESULT]: "This Result must be used. Handle the error case or explicitly discard it with `void`.",
+            [MessageId.ADD_VOID]: "Explicitly discard the Result with `void`.",
         },
         schema: [],
     },
@@ -38,32 +40,33 @@ export const noUnusedResult = createRule({
     create(context) {
         const services = ESLintUtils.getParserServices(context);
         const checker = services.program.getTypeChecker();
-        function checkExpression(node) {
+        function checkExpression(node, statement) {
             switch (node.type) {
                 case "UnaryExpression":
                     if (node.operator === "void") {
                         return;
                     }
-                    break;
+                    checkExpression(node.argument, statement);
+                    return;
                 case "ConditionalExpression":
-                    checkExpression(node.consequent);
-                    checkExpression(node.alternate);
+                    checkExpression(node.consequent, statement);
+                    checkExpression(node.alternate, statement);
                     return;
                 case "LogicalExpression":
-                    checkExpression(node.left);
-                    checkExpression(node.right);
+                    checkExpression(node.left, statement);
+                    checkExpression(node.right, statement);
                     return;
                 case "SequenceExpression":
                     for (const expr of node.expressions) {
-                        checkExpression(expr);
+                        checkExpression(expr, statement);
                     }
                     return;
                 case "TSAsExpression":
                 case "TSNonNullExpression":
-                    checkExpression(node.expression);
+                    checkExpression(node.expression, statement);
                     return;
                 case "ChainExpression":
-                    checkExpression(node.expression);
+                    checkExpression(node.expression, statement);
                     return;
             }
             const tsNode = services.esTreeNodeToTSNodeMap.get(node);
@@ -73,12 +76,24 @@ export const noUnusedResult = createRule({
             }
             context.report({
                 node,
-                messageId: "unusedResult",
+                messageId: MessageId.UNUSED_RESULT,
+                suggest: [
+                    {
+                        messageId: MessageId.ADD_VOID,
+                        fix(fixer) {
+                            const expr = statement.expression;
+                            if (needsParentheses(expr)) {
+                                return [fixer.insertTextBefore(expr, "void ("), fixer.insertTextAfter(expr, ")")];
+                            }
+                            return fixer.insertTextBefore(expr, "void ");
+                        },
+                    },
+                ],
             });
         }
         return {
             ExpressionStatement(node) {
-                checkExpression(node.expression);
+                checkExpression(node.expression, node);
             },
         };
     },

package/dist/rules/utils/result-type.d.ts

@@ -0,0 +1,19 @@
+import ts from "typescript";
+export declare const ResultVariant: {
+    readonly NONE: "none";
+    readonly OK: "ok";
+    readonly ERR: "err";
+    readonly MIXED: "mixed";
+};
+export type ResultVariant = (typeof ResultVariant)[keyof typeof ResultVariant];
+export declare function getResultVariant(type: ts.Type): ResultVariant;
+/**
+ * Determines whether a type originates from antithrow's `Result` family.
+ *
+ * `Result<T, E>` is a union of `Ok<T, E> | Err<T, E>`, so we recurse into
+ * union members. We also guard against `any`/`unknown`/`never` to avoid
+ * false positives on untyped code. Finally, we verify the symbol's
+ * declaration lives inside the `antithrow` package so that unrelated types
+ * with the same names (e.g. a user-defined `Ok` class) are not flagged.
+ */
+export declare function isResultType(type: ts.Type): boolean;

package/dist/rules/utils/result-type.js

@@ -0,0 +1,77 @@
+import ts from "typescript";
+const RESULT_TYPE_NAMES = new Set(["Ok", "Err", "ResultAsync"]);
+const FIXABLE_OK_TYPE_NAMES = new Set(["Ok"]);
+const FIXABLE_ERR_TYPE_NAMES = new Set(["Err"]);
+const NULLISH_TYPE_FLAGS = ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Void;
+export const ResultVariant = {
+    NONE: "none",
+    OK: "ok",
+    ERR: "err",
+    MIXED: "mixed",
+};
+function isAntithrowResultTypeSymbol(symbol) {
+    if (!RESULT_TYPE_NAMES.has(symbol.getName())) {
+        return false;
+    }
+    const declarations = symbol.getDeclarations() ?? [];
+    return declarations.some((decl) => {
+        const sourceFile = decl.getSourceFile();
+        return sourceFile.fileName.includes("antithrow");
+    });
+}
+function collectResultTypes(type, collection) {
+    if (type.isUnion()) {
+        for (const member of type.types) {
+            collectResultTypes(member, collection);
+        }
+        return;
+    }
+    const flags = type.getFlags();
+    if (flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never | NULLISH_TYPE_FLAGS)) {
+        return;
+    }
+    const symbol = type.getSymbol();
+    if (!symbol || !isAntithrowResultTypeSymbol(symbol)) {
+        collection.hasNonResultMembers = true;
+        return;
+    }
+    collection.names.add(symbol.getName());
+}
+export function getResultVariant(type) {
+    const collection = {
+        hasNonResultMembers: false,
+        names: new Set(),
+    };
+    collectResultTypes(type, collection);
+    const { names } = collection;
+    if (names.size === 0) {
+        return ResultVariant.NONE;
+    }
+    if (collection.hasNonResultMembers) {
+        return ResultVariant.MIXED;
+    }
+    if (names.has("ResultAsync")) {
+        return ResultVariant.MIXED;
+    }
+    const isOnlyOk = [...names].every((name) => FIXABLE_OK_TYPE_NAMES.has(name));
+    if (isOnlyOk) {
+        return ResultVariant.OK;
+    }
+    const isOnlyErr = [...names].every((name) => FIXABLE_ERR_TYPE_NAMES.has(name));
+    if (isOnlyErr) {
+        return ResultVariant.ERR;
+    }
+    return ResultVariant.MIXED;
+}
+/**
+ * Determines whether a type originates from antithrow's `Result` family.
+ *
+ * `Result<T, E>` is a union of `Ok<T, E> | Err<T, E>`, so we recurse into
+ * union members. We also guard against `any`/`unknown`/`never` to avoid
+ * false positives on untyped code. Finally, we verify the symbol's
+ * declaration lives inside the `antithrow` package so that unrelated types
+ * with the same names (e.g. a user-defined `Ok` class) are not flagged.
+ */
+export function isResultType(type) {
+    return getResultVariant(type) !== ResultVariant.NONE;
+}

package/dist/rules/utils/test-utils.d.ts

@@ -0,0 +1,3 @@
+import { RuleTester } from "@typescript-eslint/rule-tester";
+export declare const ruleTester: RuleTester;
+export declare function createCodeHelper(preamble: string): (strings: TemplateStringsArray, ...values: unknown[]) => string;

package/dist/rules/utils/test-utils.js

@@ -0,0 +1,26 @@
+import { afterAll, describe, test } from "bun:test";
+import { RuleTester } from "@typescript-eslint/rule-tester";
+RuleTester.describe = describe;
+RuleTester.describeSkip = describe.skip;
+RuleTester.it = test;
+RuleTester.itSkip = test.skip;
+RuleTester.afterAll = afterAll;
+export const ruleTester = new RuleTester({
+    languageOptions: {
+        parserOptions: {
+            projectService: {
+                allowDefaultProject: ["*.ts"],
+            },
+            tsconfigRootDir: import.meta.dirname,
+        },
+    },
+});
+export function createCodeHelper(preamble) {
+    return (strings, ...values) => {
+        let body = strings[0] ?? "";
+        for (const [index, value] of values.entries()) {
+            body += `${String(value)}${strings[index + 1] ?? ""}`;
+        }
+        return `${preamble}${body}`;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@antithrow/eslint-plugin",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "ESLint plugin for antithrow Result types",
 	"license": "MIT",
 	"author": "Jack Weilage",