eslint-plugin-ts-type-forge 0.4.3 → 0.6.0

package/src/rules/prefer-canonical-length-constrained-tuple.test.mts

@@ -45,6 +45,21 @@ describe('prefer-canonical-length-constrained-tuple', () => {
           name: 'ignores plain arrays',
           code: 'type T = readonly string[];',
         },
+        {
+          name: 'ignores tuple patterns in a conditional type `extends` clause',
+          code: dedent`
+            type And<A extends boolean, B extends boolean> = [A, B] extends [
+              true,
+              true,
+            ]
+              ? true
+              : false;
+          `,
+        },
+        {
+          name: 'ignores tuple patterns nested in an `extends` clause',
+          code: 'type T<A> = A extends readonly (readonly [string, string])[] ? 1 : 2;',
+        },
         {
           name: 'stays silent when the target name is bound locally',
           code: dedent`
@@ -54,75 +69,116 @@ describe('prefer-canonical-length-constrained-tuple', () => {
         },
       ],
       invalid: [
+        {
+          name: 'still rewrites the branches of a conditional type',
+          code: 'type T<A> = A extends 1 ? [true, true] : 2;',
+          output: dedent`
+            import { type MutableFixedLengthTuple } from 'ts-type-forge';
+            type T<A> = A extends 1 ? MutableFixedLengthTuple<2, true> : 2;
+          `,
+          errors: [{ messageId: 'useCanonicalTuple' }],
+        },
         {
           name: 'readonly non-empty tuple',
           code: 'type T = readonly [string, ...string[]];',
-          output: 'type T = NonEmptyTuple<string>;',
+          output: dedent`
+            import { type NonEmptyTuple } from 'ts-type-forge';
+            type T = NonEmptyTuple<string>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'mutable non-empty tuple',
           code: 'type T = [string, ...string[]];',
-          output: 'type T = MutableNonEmptyTuple<string>;',
+          output: dedent`
+            import { type MutableNonEmptyTuple } from 'ts-type-forge';
+            type T = MutableNonEmptyTuple<string>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'readonly non-empty tuple with a readonly rest spelling',
           code: 'type T = readonly [string, ...(readonly string[])];',
-          output: 'type T = NonEmptyTuple<string>;',
+          output: dedent`
+            import { type NonEmptyTuple } from 'ts-type-forge';
+            type T = NonEmptyTuple<string>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'readonly fixed-length tuple',
           code: 'type T = readonly [string, string, string];',
-          output: 'type T = FixedLengthTuple<3, string>;',
+          output: dedent`
+            import { type FixedLengthTuple } from 'ts-type-forge';
+            type T = FixedLengthTuple<3, string>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'mutable fixed-length tuple',
           code: 'type T = [string, string, string];',
-          output: 'type T = MutableFixedLengthTuple<3, string>;',
+          output: dedent`
+            import { type MutableFixedLengthTuple } from 'ts-type-forge';
+            type T = MutableFixedLengthTuple<3, string>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'readonly min-length tuple',
           code: 'type T = readonly [number, number, ...number[]];',
-          output: 'type T = MinLengthTuple<2, number>;',
+          output: dedent`
+            import { type MinLengthTuple } from 'ts-type-forge';
+            type T = MinLengthTuple<2, number>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'mutable min-length tuple',
           code: 'type T = [number, number, ...number[]];',
-          output: 'type T = MutableMinLengthTuple<2, number>;',
+          output: dedent`
+            import { type MutableMinLengthTuple } from 'ts-type-forge';
+            type T = MutableMinLengthTuple<2, number>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'readonly rest spelling inside a readonly tuple',
           code: 'type T = readonly [number, number, ...(readonly number[])];',
-          output: 'type T = MinLengthTuple<2, number>;',
+          output: dedent`
+            import { type MinLengthTuple } from 'ts-type-forge';
+            type T = MinLengthTuple<2, number>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'handles the default maximum length of 10',
           code: 'type T = readonly [1, 1, 1, 1, 1, 1, 1, 1, 1, 1];',
-          output: 'type T = FixedLengthTuple<10, 1>;',
+          output: dedent`
+            import { type FixedLengthTuple } from 'ts-type-forge';
+            type T = FixedLengthTuple<10, 1>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'keeps a composite element type intact',
           code: 'type T = readonly [string | number, string | number];',
-          output: 'type T = FixedLengthTuple<2, string | number>;',
+          output: dedent`
+            import { type FixedLengthTuple } from 'ts-type-forge';
+            type T = FixedLengthTuple<2, string | number>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'handles generic element types',
           code: 'type T<V> = [V, V, ...V[]];',
-          output: 'type T<V> = MutableMinLengthTuple<2, V>;',
+          output: dedent`
+            import { type MutableMinLengthTuple } from 'ts-type-forge';
+            type T<V> = MutableMinLengthTuple<2, V>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
         {
           name: 'adds named imports once per target type',
-          options: [{ importStyle: 'named' }],
           code: dedent`
             type A = readonly [string, string];
             type B = readonly [number, number, number];
@@ -141,6 +197,13 @@ describe('prefer-canonical-length-constrained-tuple', () => {
             { messageId: 'useCanonicalTuple' },
           ],
         },
+        {
+          name: 'adds no import under importStyle: global',
+          options: [{ importStyle: 'global' }],
+          code: 'type T = readonly [string, string];',
+          output: 'type T = FixedLengthTuple<2, string>;',
+          errors: [{ messageId: 'useCanonicalTuple' }],
+        },
         {
           name: 'reuses an aliased import',
           code: dedent`
@@ -158,8 +221,11 @@ describe('prefer-canonical-length-constrained-tuple', () => {
         {
           name: 'rewrites parameter and return type positions',
           code: 'declare const f: (xs: readonly [number, number]) => [string, string];',
-          output:
-            'declare const f: (xs: FixedLengthTuple<2, number>) => MutableFixedLengthTuple<2, string>;',
+          output: dedent`
+            import { type FixedLengthTuple } from 'ts-type-forge';
+            import { type MutableFixedLengthTuple } from 'ts-type-forge';
+            declare const f: (xs: FixedLengthTuple<2, number>) => MutableFixedLengthTuple<2, string>;
+          `,
           errors: [
             { messageId: 'useCanonicalTuple' },
             { messageId: 'useCanonicalTuple' },
@@ -169,7 +235,10 @@ describe('prefer-canonical-length-constrained-tuple', () => {
           name: 'respects a raised maxLength',
           options: [{ maxLength: 12 }],
           code: 'type T = readonly [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];',
-          output: 'type T = FixedLengthTuple<12, 0>;',
+          output: dedent`
+            import { type FixedLengthTuple } from 'ts-type-forge';
+            type T = FixedLengthTuple<12, 0>;
+          `,
           errors: [{ messageId: 'useCanonicalTuple' }],
         },
       ],

package/src/rules/prefer-readonly-or-mutable-record.mts

@@ -0,0 +1,74 @@
+import { type TSESLint } from '@typescript-eslint/utils';
+import {
+  DEFAULT_IMPORT_STYLE,
+  IMPORT_STYLE_SCHEMA_PROPERTY,
+} from './import-style.mjs';
+import {
+  reportStdTypeReference,
+  type StdTypeAlternatives,
+} from './std-type-rule-utils.mjs';
+
+type Options = readonly [
+  Readonly<{
+    importStyle?: 'global' | 'named';
+  }>?,
+];
+
+type MessageIds = 'useReadonlyOrMutableRecord' | 'replaceWith';
+
+/**
+ * `Record` says nothing about whether the properties may be reassigned, so the
+ * mutability of every record type spelled with it is decided by whoever reads
+ * it. The ts-type-forge pair spells it out.
+ */
+const ALTERNATIVES: StdTypeAlternatives = new Map([
+  ['Record', ['ReadonlyRecord', 'MutableRecord']],
+]);
+
+export const preferReadonlyOrMutableRecord: TSESLint.RuleModule<
+  MessageIds,
+  Options
+> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Replace the built-in `Record` with the ts-type-forge `ReadonlyRecord` or `MutableRecord`, so that the mutability of the record is stated rather than implied.',
+    },
+    hasSuggestions: true,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          importStyle: IMPORT_STYLE_SCHEMA_PROPERTY,
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      useReadonlyOrMutableRecord:
+        'Use {{alternatives}} from ts-type-forge instead of the built-in `{{name}}`.',
+      replaceWith: 'Replace `{{name}}` with `{{replacement}}`.',
+    },
+  },
+
+  create: (context) => {
+    const importStyle = context.options[0]?.importStyle ?? DEFAULT_IMPORT_STYLE;
+
+    return {
+      TSTypeReference: (node) => {
+        reportStdTypeReference(
+          context,
+          node,
+          ALTERNATIVES,
+          {
+            report: 'useReadonlyOrMutableRecord',
+            suggestion: 'replaceWith',
+          },
+          importStyle,
+        );
+      },
+    };
+  },
+  defaultOptions: [{ importStyle: DEFAULT_IMPORT_STYLE }],
+} as const;

package/src/rules/prefer-readonly-or-mutable-record.test.mts

@@ -0,0 +1,160 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferReadonlyOrMutableRecord } from './prefer-readonly-or-mutable-record.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+  },
+});
+
+describe('prefer-readonly-or-mutable-record', () => {
+  tester.run(
+    'prefer-readonly-or-mutable-record',
+    preferReadonlyOrMutableRecord,
+    {
+      valid: [
+        {
+          name: 'accepts the ts-type-forge counterparts',
+          code: dedent`
+            type A = ReadonlyRecord<string, number>;
+            type B = MutableRecord<'a' | 'b', number>;
+          `,
+        },
+        {
+          name: 'ignores unrelated standard-library types',
+          code: 'type A = Readonly<Partial<{ a: 1 }>>;',
+        },
+        {
+          name: 'ignores a qualified name that merely ends in `Record`',
+          code: 'type A = Lib.Record<string, number>;',
+        },
+        {
+          name: 'ignores a locally declared type of the same name',
+          code: dedent`
+            type Record<K extends PropertyKey, V> = { readonly [P in K]: V };
+            type A = Record<string, number>;
+          `,
+        },
+        {
+          name: 'ignores a name imported from another module',
+          code: dedent`
+            import { type Record } from './my-types.mjs';
+            type A = Record<string, number>;
+          `,
+        },
+      ],
+      invalid: [
+        {
+          name: 'reports `Record` and suggests both counterparts',
+          code: 'type A = Record<string, number>;',
+          errors: [
+            {
+              messageId: 'useReadonlyOrMutableRecord',
+              data: {
+                name: 'Record',
+                alternatives: '`ReadonlyRecord` or `MutableRecord`',
+              },
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Record', replacement: 'ReadonlyRecord' },
+                  output: dedent`
+                    import { type ReadonlyRecord } from 'ts-type-forge';
+                    type A = ReadonlyRecord<string, number>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Record', replacement: 'MutableRecord' },
+                  output: dedent`
+                    import { type MutableRecord } from 'ts-type-forge';
+                    type A = MutableRecord<string, number>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'touches no import under the `global` import style',
+          options: [{ importStyle: 'global' }],
+          code: 'type A = Record<string, number>;',
+          errors: [
+            {
+              messageId: 'useReadonlyOrMutableRecord',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: 'type A = ReadonlyRecord<string, number>;',
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: 'type A = MutableRecord<string, number>;',
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'reuses an existing ts-type-forge import, alias included',
+          code: dedent`
+            import { type ReadonlyRecord as RRecord } from 'ts-type-forge';
+            type A = Record<string, number>;
+          `,
+          errors: [
+            {
+              messageId: 'useReadonlyOrMutableRecord',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Record', replacement: 'RRecord' },
+                  output: dedent`
+                    import { type ReadonlyRecord as RRecord } from 'ts-type-forge';
+                    type A = RRecord<string, number>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Record', replacement: 'MutableRecord' },
+                  output: dedent`
+                    import { type MutableRecord } from 'ts-type-forge';
+                    import { type ReadonlyRecord as RRecord } from 'ts-type-forge';
+                    type A = MutableRecord<string, number>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'reports `Record` in a type-parameter constraint too',
+          code: 'type A<T extends Record<string, unknown>> = keyof T;',
+          errors: [
+            {
+              messageId: 'useReadonlyOrMutableRecord',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type ReadonlyRecord } from 'ts-type-forge';
+                    type A<T extends ReadonlyRecord<string, unknown>> = keyof T;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type MutableRecord } from 'ts-type-forge';
+                    type A<T extends MutableRecord<string, unknown>> = keyof T;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  );
+});

package/src/rules/prefer-strict-or-relaxed-utility-type.mts

@@ -0,0 +1,80 @@
+import { type TSESLint } from '@typescript-eslint/utils';
+import {
+  DEFAULT_IMPORT_STYLE,
+  IMPORT_STYLE_SCHEMA_PROPERTY,
+} from './import-style.mjs';
+import {
+  reportStdTypeReference,
+  type StdTypeAlternatives,
+} from './std-type-rule-utils.mjs';
+
+type Options = readonly [
+  Readonly<{
+    importStyle?: 'global' | 'named';
+  }>?,
+];
+
+type MessageIds = 'useStrictOrRelaxed' | 'replaceWith';
+
+/**
+ * The standard-library types whose second argument is unchecked, and the
+ * ts-type-forge pair that makes the choice explicit.
+ *
+ * `Strict*` constrains the second argument (`U extends T` / `K extends keyof T`),
+ * so a key that does not exist — typically a leftover after a rename — is a
+ * compile error instead of a silently empty result. `Relaxed*` keeps the
+ * standard-library behavior for the cases that genuinely need it (a subtrahend
+ * that is not provably part of the union, a key set computed from a still
+ * deferred type parameter).
+ */
+const ALTERNATIVES: StdTypeAlternatives = new Map([
+  ['Exclude', ['StrictExclude', 'RelaxedExclude']],
+  ['Extract', ['StrictExtract', 'RelaxedExtract']],
+  ['Omit', ['StrictOmit', 'RelaxedOmit']],
+  ['Pick', ['StrictPick', 'RelaxedPick']],
+]);
+
+export const preferStrictOrRelaxedUtilityType: TSESLint.RuleModule<
+  MessageIds,
+  Options
+> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Replace the built-in `Exclude` / `Extract` / `Omit` / `Pick` with the ts-type-forge `Strict*` or `Relaxed*` counterpart, so that the unchecked second argument becomes an explicit choice.',
+    },
+    hasSuggestions: true,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          importStyle: IMPORT_STYLE_SCHEMA_PROPERTY,
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      useStrictOrRelaxed:
+        'Use {{alternatives}} from ts-type-forge instead of the built-in `{{name}}`.',
+      replaceWith: 'Replace `{{name}}` with `{{replacement}}`.',
+    },
+  },
+
+  create: (context) => {
+    const importStyle = context.options[0]?.importStyle ?? DEFAULT_IMPORT_STYLE;
+
+    return {
+      TSTypeReference: (node) => {
+        reportStdTypeReference(
+          context,
+          node,
+          ALTERNATIVES,
+          { report: 'useStrictOrRelaxed', suggestion: 'replaceWith' },
+          importStyle,
+        );
+      },
+    };
+  },
+  defaultOptions: [{ importStyle: DEFAULT_IMPORT_STYLE }],
+} as const;