typescript-eslint · JoshuaKGoldberg · Nov 14, 2024 · Sep 24, 2024 · Sep 24, 2024 · Sep 24, 2024
diff --git a/packages/eslint-plugin/docs/rules/no-unsafe-type-assertion.mdx b/packages/eslint-plugin/docs/rules/no-unsafe-type-assertion.mdx
@@ -0,0 +1,63 @@
+---
+description: 'Disallow type assertions that narrow a type.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unsafe-type-assertion** for documentation.
+
+Type assertions are a way to tell TypeScript what the type of a value is. This can be useful but also unsafe if you use type assertions to narrow down a type.
+
+This rule forbids using type assertions to narrow a type, as this bypasses TypeScript's type-checking. Type assertions that broaden a type are safe because TypeScript essentially knows _less_ about a type.
+
+Instead of using type assertions to narrow a type, it's better to rely on type guards, which help avoid potential runtime errors caused by unsafe type assertions.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+function f() {
+  return Math.random() < 0.5 ? 42 : 'oops';
+}
+
+const z = f() as number;
+
+const items = [1, '2', 3, '4'];
+
+const number = items[0] as number;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+function f() {
+  return Math.random() < 0.5 ? 42 : 'oops';
+}
+
+const z = f() as number | string | boolean;
+
 const items = [1, '2', 3, '4'];
+
+const number = items[0] as number | string | undefined;
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If your codebase has many unsafe type assertions, then it may be difficult to enable this rule.
+It may be easier to skip the `no-unsafe-*` rules pending increasing type safety in unsafe areas of your project.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
+
+If your project frequently stubs objects in test files, the rule may trigger a lot of reports. Consider disabling the rule for such files to reduce frequent warnings.
+
+## Further Reading
+
+- More on TypeScript's [type assertions](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions)
diff --git a/packages/eslint-plugin/src/configs/all.ts b/packages/eslint-plugin/src/configs/all.ts
@@ -106,6 +106,7 @@ export = {
     '@typescript-eslint/no-unsafe-function-type': 'error',
     '@typescript-eslint/no-unsafe-member-access': 'error',
     '@typescript-eslint/no-unsafe-return': 'error',
+    '@typescript-eslint/no-unsafe-type-assertion': 'error',
     '@typescript-eslint/no-unsafe-unary-minus': 'error',
     'no-unused-expressions': 'off',
     '@typescript-eslint/no-unused-expressions': 'error',

diff --git a/packages/eslint-plugin/src/configs/disable-type-checked.ts b/packages/eslint-plugin/src/configs/disable-type-checked.ts
@@ -40,6 +40,7 @@ export = {
     '@typescript-eslint/no-unsafe-enum-comparison': 'off',
     '@typescript-eslint/no-unsafe-member-access': 'off',
     '@typescript-eslint/no-unsafe-return': 'off',
+    '@typescript-eslint/no-unsafe-type-assertion': 'off',
     '@typescript-eslint/no-unsafe-unary-minus': 'off',
     '@typescript-eslint/non-nullable-type-assertion-style': 'off',
     '@typescript-eslint/only-throw-error': 'off',

diff --git a/packages/eslint-plugin/src/rules/index.ts b/packages/eslint-plugin/src/rules/index.ts
@@ -83,6 +83,7 @@ import noUnsafeEnumComparison from './no-unsafe-enum-comparison';
 import noUnsafeFunctionType from './no-unsafe-function-type';
 import noUnsafeMemberAccess from './no-unsafe-member-access';
 import noUnsafeReturn from './no-unsafe-return';
+import noUnsafeTypeAssertion from './no-unsafe-type-assertion';
 import noUnsafeUnaryMinus from './no-unsafe-unary-minus';
 import noUnusedExpressions from './no-unused-expressions';
 import noUnusedVars from './no-unused-vars';
@@ -213,6 +214,7 @@ const rules = {
   'no-unsafe-function-type': noUnsafeFunctionType,
   'no-unsafe-member-access': noUnsafeMemberAccess,
   'no-unsafe-return': noUnsafeReturn,
+  'no-unsafe-type-assertion': noUnsafeTypeAssertion,
   'no-unsafe-unary-minus': noUnsafeUnaryMinus,
   'no-unused-expressions': noUnusedExpressions,
   'no-unused-vars': noUnusedVars,

diff --git a/packages/eslint-plugin/src/rules/no-unsafe-type-assertion.ts b/packages/eslint-plugin/src/rules/no-unsafe-type-assertion.ts
@@ -0,0 +1,146 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+
+import * as tsutils from 'ts-api-utils';
+import * as ts from 'typescript';
+
+import {
+  createRule,
+  getConstrainedTypeAtLocation,
+  getParserServices,
+  isTypeAnyType,
+  isTypeUnknownType,
+  isUnsafeAssignment,
+} from '../util';
+
+export default createRule({
+  name: 'no-unsafe-type-assertion',
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow type assertions that narrow a type',
+      requiresTypeChecking: true,
+    },
+    messages: {
+      unsafeOfAnyTypeAssertion:
+        'Unsafe cast from {{type}} detected: consider using type guards or a safer cast.',
+      unsafeToAnyTypeAssertion:
+        'Unsafe cast to {{type}} detected: consider using a more specific type to ensure safety.',
+      unsafeTypeAssertion:
+        "Unsafe type assertion: type '{{type}}' is more narrow than the original type.",
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+  create(context) {
+    const services = getParserServices(context);
+    const checker = services.program.getTypeChecker();
+
+    function getAnyTypeName(type: ts.Type): string {
+      return tsutils.isIntrinsicErrorType(type) ? 'error typed' : '`any`';
+    }
+
+    function isObjectLiteralType(type: ts.Type): boolean {
+      return (
+        tsutils.isObjectType(type) &&
+        tsutils.isObjectFlagSet(type, ts.ObjectFlags.ObjectLiteral)
+      );
+    }
+
+    function checkExpression(
+      node: TSESTree.TSAsExpression | TSESTree.TSTypeAssertion,
+    ): void {
+      const expressionType = getConstrainedTypeAtLocation(
+        services,
+        node.expression,
+      );
+      const assertedType = getConstrainedTypeAtLocation(
+        services,
+        node.typeAnnotation,
+      );
+
+      if (expressionType === assertedType) {
+        return;
+      }
+
+      // handle cases when casting unknown ==> any.
+      if (isTypeAnyType(assertedType) && isTypeUnknownType(expressionType)) {
+        context.report({
+          node,
+          messageId: 'unsafeToAnyTypeAssertion',
+          data: {
+            type: '`any`',
+          },
+        });
+
+        return;
+      }
+
+      const unsafeExpressionAny = isUnsafeAssignment(
+        expressionType,
+        assertedType,
+        checker,
+        node.expression,
+      );
+
+      if (unsafeExpressionAny) {
+        context.report({
+          node,
+          messageId: 'unsafeOfAnyTypeAssertion',
+          data: {
+            type: getAnyTypeName(unsafeExpressionAny.sender),
+          },
+        });
+
+        return;
+      }
+
+      const unsafeAssertedAny = isUnsafeAssignment(
+        assertedType,
+        expressionType,
+        checker,
+        node.typeAnnotation,
+      );
+
+      if (unsafeAssertedAny) {
+        context.report({
+          node,
+          messageId: 'unsafeToAnyTypeAssertion',
+          data: {
+            type: getAnyTypeName(unsafeAssertedAny.sender),
+          },
+        });
+
+        return;
+      }
+
+      // Use the widened type in case of an object literal so `isTypeAssignableTo()`
+      // won't fail on excess property check.
+      const nodeWidenedType = isObjectLiteralType(expressionType)
+        ? checker.getWidenedType(expressionType)
+        : expressionType;
+
+      const isAssertionSafe = checker.isTypeAssignableTo(
+        nodeWidenedType,
+        assertedType,
+      );
+
+      if (!isAssertionSafe) {
+        context.report({
+          node,
+          messageId: 'unsafeTypeAssertion',
+          data: {
+            type: checker.typeToString(assertedType),
+          },
+        });
+      }
+    }
+
+    return {
+      'TSAsExpression, TSTypeAssertion'(
+        node: TSESTree.TSAsExpression | TSESTree.TSTypeAssertion,
+      ): void {
+        checkExpression(node);
+      },
+    };
+  },
+});
diff --git a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-type-assertion.shot b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unsafe-type-assertion.shot