typescript-eslint · JoshuaKGoldberg · Mar 20, 2023 · Jan 12, 2022 · Jan 13, 2022 · Jan 13, 2022
diff --git a/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.md b/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.md
@@ -129,6 +129,101 @@ interface Foo {
 
 ## Options
 
+### `allow`
+
+Some complex types cannot easily be made readonly, for example the `HTMLElement` type or the `JQueryStatic` type from `@types/jquery`. This option allows you to globally disable reporting of such types.
+
+Each item must be one of:
+
+- A type defined in a file (`{from: "file", name: "Foo", path: "src/foo-file.ts"}` with `path` being an optional path relative to the project root directory)
+- A type from the default library (`{from: "lib", name: "Foo"}`)
+- A type from a package (`{from: "package", name: "Foo", package: "foo-lib"}`, this also works for types defined in a typings package).
+
+Additionally, a type may be defined just as a simple string, which then matches the type independently of its origin.
+
+Examples of code for this rule with:
+
+```json
+{
+  "allow": [
+    "$",
+    { "source": "file", "name": "Foo" },
+    { "source": "lib", "name": "HTMLElement" },
+    { "from": "package", "name": "Bar", "package": "bar-lib" }
+  ]
+}
+```
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+interface ThisIsMutable {
+  prop: string;
+}
+
+interface Wrapper {
+  sub: ThisIsMutable;
+}
+
+interface WrapperWithOther {
+  readonly sub: Foo;
+  otherProp: string;
+}
+
+function fn1(arg: ThisIsMutable) {} // Incorrect because ThisIsMutable is not readonly
+function fn2(arg: Wrapper) {} // Incorrect because Wrapper.sub is not readonly
+function fn3(arg: WrapperWithOther) {} // Incorrect because WrapperWithOther.otherProp is not readonly and not in the allowlist
+```
+
+```ts
+import { Foo } from 'some-lib';
+import { Bar } from 'incorrect-lib';
+
+interface HTMLElement {
+  prop: string;
+}
+
+function fn1(arg: Foo) {} // Incorrect because Foo is not a local type
+function fn2(arg: HTMLElement) {} // Incorrect because HTMLElement is not from the default library
+function fn3(arg: Bar) {} // Incorrect because Bar is not from "bar-lib"
+```
+
+#### ✅ Correct
+
+```ts
+interface Foo {
+  prop: string;
+}
+
+interface Wrapper {
+  readonly sub: Foo;
+  readonly otherProp: string;
+}
+
+function fn1(arg: Foo) {} // Works because Foo is allowed
+function fn2(arg: Wrapper) {} // Works even when Foo is nested somewhere in the type, with other properties still being checked
+```
+
+```ts
+import { Bar } from 'bar-lib';
+
+interface Foo {
+  prop: string;
+}
+
+function fn1(arg: Foo) {} // Works because Foo is a local type
+function fn2(arg: HTMLElement) {} // Works because HTMLElement is from the default library
+function fn3(arg: Bar) {} // Works because Bar is from "bar-lib"
+```
+
+```ts
+import { Foo } from './foo';
+
+function fn(arg: Foo) {} // Works because Foo is still a local type - it has to be in the same package
+```
+
 ### `checkParameterProperties`
 
 This option allows you to enable or disable the checking of parameter properties.

diff --git a/packages/eslint-plugin/src/rules/prefer-readonly-parameter-types.ts b/packages/eslint-plugin/src/rules/prefer-readonly-parameter-types.ts
@@ -5,9 +5,11 @@ import * as util from '../util';
 
 type Options = [
   {
+    allow?: util.TypeOrValueSpecifier[];
     checkParameterProperties?: boolean;
     ignoreInferredTypes?: boolean;
-  } & util.ReadonlynessOptions,
+    treatMethodsAsReadonly?: boolean;
+  },
 ];
 type MessageIds = 'shouldBeReadonly';
 
@@ -25,13 +27,15 @@ export default util.createRule<Options, MessageIds>({
         type: 'object',
         additionalProperties: false,
         properties: {
+          allow: util.readonlynessOptionsSchema.properties.allow,
           checkParameterProperties: {
             type: 'boolean',
           },
           ignoreInferredTypes: {
             type: 'boolean',
           },
-          ...util.readonlynessOptionsSchema.properties,
+          treatMethodsAsReadonly:
+            util.readonlynessOptionsSchema.properties.treatMethodsAsReadonly,
         },
       },
     ],
@@ -41,17 +45,25 @@ export default util.createRule<Options, MessageIds>({
   },
   defaultOptions: [
     {
+      allow: util.readonlynessOptionsDefaults.allow,
       checkParameterProperties: true,
       ignoreInferredTypes: false,
-      ...util.readonlynessOptionsDefaults,
+      treatMethodsAsReadonly:
+        util.readonlynessOptionsDefaults.treatMethodsAsReadonly,
     },
   ],
   create(
     context,
-    [{ checkParameterProperties, ignoreInferredTypes, treatMethodsAsReadonly }],
+    [
+      {
+        allow,
+        checkParameterProperties,
+        ignoreInferredTypes,
+        treatMethodsAsReadonly,
+      },
+    ],
   ) {
     const services = util.getParserServices(context);
-    const checker = services.program.getTypeChecker();
 
     return {
       [[
@@ -94,8 +106,9 @@ export default util.createRule<Options, MessageIds>({
           }
 
           const type = services.getTypeAtLocation(actualParam);
-          const isReadOnly = util.isTypeReadonly(checker, type, {
+          const isReadOnly = util.isTypeReadonly(services.program, type, {
             treatMethodsAsReadonly: treatMethodsAsReadonly!,
+            allow,
           });
 
           if (!isReadOnly) {

diff --git a/packages/eslint-plugin/tests/rules/prefer-readonly-parameter-types.test.ts b/packages/eslint-plugin/tests/rules/prefer-readonly-parameter-types.test.ts
@@ -401,6 +401,83 @@ ruleTester.run('prefer-readonly-parameter-types', rule, {
         },
       ],
     },
+    // Allowlist
+    {
+      code: `
+        interface Foo {
+          readonly prop: RegExp;
+        }
+
+        function foo(arg: Foo) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'lib', name: 'RegExp' }],
+        },
+      ],
+    },
+    {
+      code: `
+        interface Foo {
+          prop: RegExp;
+        }
+
+        function foo(arg: Readonly<Foo>) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'lib', name: 'RegExp' }],
+        },
+      ],
+    },
+    {
+      code: `
+        interface Foo {
+          prop: string;
+        }
+
+        function foo(arg: Foo) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'file', name: 'Foo' }],
+        },
+      ],
+    },
+    {
+      code: `
+        interface Bar {
+          prop: string;
+        }
+        interface Foo {
+          readonly prop: Bar;
+        }
+
+        function foo(arg: Foo) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'file', name: 'Foo' }],
+        },
+      ],
+    },
+    {
+      code: `
+        interface Bar {
+          prop: string;
+        }
+        interface Foo {
+          readonly prop: Bar;
+        }
+
+        function foo(arg: Foo) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'file', name: 'Bar' }],
+        },
+      ],
+    },
   ],
   invalid: [
     // arrays
@@ -885,5 +962,126 @@ ruleTester.run('prefer-readonly-parameter-types', rule, {
       `,
       errors: [{ line: 6, messageId: 'shouldBeReadonly' }],
     },
+    // Allowlist
+    {
+      code: `
+        function foo(arg: RegExp) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'file', name: 'Foo' }],
+        },
+      ],
+      errors: [
+        {
+          messageId: 'shouldBeReadonly',
+          line: 2,
+          column: 22,
+          endColumn: 33,
+        },
+      ],
+    },
+    {
+      code: `
+        interface Foo {
+          readonly prop: RegExp;
+        }
+
+        function foo(arg: Foo) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'file', name: 'Bar' }],
+        },
+      ],
+      errors: [
+        {
+          messageId: 'shouldBeReadonly',
+          line: 6,
+          column: 22,
+          endColumn: 30,
+        },
+      ],
+    },
+    {
+      code: `
+        interface Foo {
+          readonly prop: RegExp;
+        }
+
+        function foo(arg: Foo) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'lib', name: 'Foo' }],
+        },
+      ],
+      errors: [
+        {
+          messageId: 'shouldBeReadonly',
+          line: 6,
+          column: 22,
+          endColumn: 30,
+        },
+      ],
+    },
+    {
+      code: `
+        interface Foo {
+          readonly prop: RegExp;
+        }
+
+        function foo(arg: Foo) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'package', name: 'Foo', package: 'foo-lib' }],
+        },
+      ],
+      errors: [
+        {
+          messageId: 'shouldBeReadonly',
+          line: 6,
+          column: 22,
+          endColumn: 30,
+        },
+      ],
+    },
+    {
+      code: `
+        function foo(arg: RegExp) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'file', name: 'RegExp' }],
+        },
+      ],
+      errors: [
+        {
+          messageId: 'shouldBeReadonly',
+          line: 2,
+          column: 22,
+          endColumn: 33,
+        },
+      ],
+    },
+    {
+      code: `
+        function foo(arg: RegExp) {}
+      `,
+      options: [
+        {
+          allow: [{ from: 'package', name: 'RegExp', package: 'regexp-lib' }],
+        },
+      ],
+      errors: [
+        {
+          messageId: 'shouldBeReadonly',
+          line: 2,
+          column: 22,
+          endColumn: 33,
+        },
+      ],
+    },
   ],
 });
diff --git a/packages/type-utils/package.json b/packages/type-utils/package.json
@@ -52,6 +52,7 @@
   },
   "devDependencies": {
     "@typescript-eslint/parser": "5.55.0",
+    "ajv": "^8.12.0",
     "typescript": "*"
   },
   "peerDependencies": {