eslint-plugin-ts-type-forge 0.6.6 → 0.7.1

package/src/rules/prefer-canonical-mutable-record.test.mts

@@ -0,0 +1,164 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferCanonicalMutableRecord } from './prefer-canonical-mutable-record.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+  },
+});
+
+describe('prefer-canonical-mutable-record', () => {
+  tester.run('prefer-canonical-mutable-record', preferCanonicalMutableRecord, {
+    valid: [
+      {
+        name: 'accepts the canonical spelling',
+        code: 'type A = MutableRecord<string, number>;',
+      },
+      {
+        name: 'ignores `Mutable` applied to a non-record type',
+        code: 'type A = Mutable<{ a: number }>;',
+      },
+      {
+        name: 'ignores a bare `Record` (prefer-readonly-or-mutable-record owns it)',
+        code: 'type A = Record<string, number>;',
+      },
+      {
+        name: 'ignores a qualified `Mutable`',
+        code: 'type A = Lib.Mutable<Record<string, number>>;',
+      },
+      {
+        name: 'ignores a locally declared `Mutable`',
+        code: dedent`
+          type Mutable<T> = { -readonly [P in keyof T]?: T[P] };
+          type A = Mutable<Record<string, number>>;
+        `,
+      },
+      {
+        name: 'ignores a `Mutable` imported from another module',
+        code: dedent`
+          import { type Mutable } from './my-types.mjs';
+          type A = Mutable<Record<string, number>>;
+        `,
+      },
+      {
+        name: 'ignores a wrapped `Record` that is declared locally',
+        code: dedent`
+          type Record<K extends PropertyKey, V> = { readonly [P in K]: V };
+          type A = Mutable<Record<string, number>>;
+        `,
+      },
+      {
+        name: 'stays silent when `MutableRecord` is bound to another module',
+        code: dedent`
+          import { type MutableRecord } from './my-types.mjs';
+          type A = Mutable<Record<string, number>>;
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'rewrites `Mutable<Record<K, V>>`',
+        code: 'type A = Mutable<Record<string, number>>;',
+        output: dedent`
+          import { type MutableRecord } from 'ts-type-forge';
+          type A = MutableRecord<string, number>;
+        `,
+        errors: [
+          {
+            messageId: 'useMutableRecord',
+            data: {
+              original: 'Mutable<Record<string, number>>',
+              replacement: 'MutableRecord<string, number>',
+            },
+          },
+        ],
+      },
+      {
+        name: 'rewrites `Mutable<ReadonlyRecord<K, V>>`',
+        code: "type A = Mutable<ReadonlyRecord<'a' | 'b', number>>;",
+        output: dedent`
+          import { type MutableRecord } from 'ts-type-forge';
+          type A = MutableRecord<'a' | 'b', number>;
+        `,
+        errors: [{ messageId: 'useMutableRecord' }],
+      },
+      {
+        name: 'unwraps the redundant `Mutable<MutableRecord<K, V>>`',
+        code: 'type A = Mutable<MutableRecord<string, number>>;',
+        output: dedent`
+          import { type MutableRecord } from 'ts-type-forge';
+          type A = MutableRecord<string, number>;
+        `,
+        errors: [{ messageId: 'useMutableRecord' }],
+      },
+      {
+        name: 'touches no import under the `global` import style',
+        options: [{ importStyle: 'global' }],
+        code: 'type A = Mutable<Record<string, number>>;',
+        output: 'type A = MutableRecord<string, number>;',
+        errors: [{ messageId: 'useMutableRecord' }],
+      },
+      {
+        name: 'adds the import once for multiple rewrites',
+        code: dedent`
+          type A = Mutable<Record<string, number>>;
+          type B = Mutable<ReadonlyRecord<string, boolean>>;
+        `,
+        output: dedent`
+          import { type MutableRecord } from 'ts-type-forge';
+          type A = MutableRecord<string, number>;
+          type B = MutableRecord<string, boolean>;
+        `,
+        errors: [
+          { messageId: 'useMutableRecord' },
+          { messageId: 'useMutableRecord' },
+        ],
+      },
+      {
+        name: 'follows ts-type-forge import aliases on both sides',
+        code: dedent`
+          import { type Mutable as Mut, type MutableRecord as MRecord } from 'ts-type-forge';
+          type A = Mut<Record<string, number>>;
+        `,
+        output: dedent`
+          import { type Mutable as Mut, type MutableRecord as MRecord } from 'ts-type-forge';
+          type A = MRecord<string, number>;
+        `,
+        errors: [
+          {
+            messageId: 'useMutableRecord',
+            data: {
+              original: 'Mut<Record<string, number>>',
+              replacement: 'MRecord<string, number>',
+            },
+          },
+        ],
+      },
+      {
+        name: 'rewrites the outer occurrence first when nested',
+        options: [{ importStyle: 'global' }],
+        code: 'type A = Mutable<Record<string, Mutable<Record<string, number>>>>;',
+        // The two fixes overlap, so the first pass applies only the outer one
+        // and the next pass reaches the fixed point.
+        output: [
+          'type A = MutableRecord<string, Mutable<Record<string, number>>>;',
+          'type A = MutableRecord<string, MutableRecord<string, number>>;',
+        ],
+        errors: [
+          { messageId: 'useMutableRecord' },
+          { messageId: 'useMutableRecord' },
+        ],
+      },
+      {
+        name: 'rewrites inside a larger type',
+        options: [{ importStyle: 'global' }],
+        code: 'type A = readonly Mutable<Record<string, number>>[];',
+        output: 'type A = readonly MutableRecord<string, number>[];',
+        errors: [{ messageId: 'useMutableRecord' }],
+      },
+    ],
+  });
+});

package/src/rules/{tuple-rule-utils.mts → rewrite-rule-utils.mts}

@@ -5,7 +5,8 @@ import { buildTypeImportFix } from './import-utils.mjs';
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
 
-export type TupleRewrite = Readonly<{
+/** One deterministic replacement of a type node by a named ts-type-forge type. */
+export type TypeRewrite = Readonly<{
   node: TSESTree.Node;
   canonicalName: string;
   /** Text inside the `<...>` of the replacement, e.g. `'2, string'`. */
@@ -21,9 +22,9 @@ export type TupleRewrite = Readonly<{
  * span — so spreading them across reports makes the fixes conflict and only one
  * survives per pass.
  */
-export const reportTupleRewrites = <MessageIds extends string>(
+export const reportTypeRewrites = <MessageIds extends string>(
   context: TSESLint.RuleContext<MessageIds, readonly unknown[]>,
-  rewrites: readonly TupleRewrite[],
+  rewrites: readonly TypeRewrite[],
   messageId: MessageIds,
   importStyle: ImportStyle,
 ): void => {

package/src/rules/rules.mts

@@ -1,11 +1,13 @@
 import { type ESLintPlugin } from '../types.mjs';
 import { preferCanonicalLengthConstrainedTuple } from './prefer-canonical-length-constrained-tuple.mjs';
+import { preferCanonicalMutableRecord } from './prefer-canonical-mutable-record.mjs';
 import { preferReadonlyOrMutableRecord } from './prefer-readonly-or-mutable-record.mjs';
 import { preferStrictOrRelaxedUtilityType } from './prefer-strict-or-relaxed-utility-type.mjs';
 
 export const tsTypeForgeRules = {
   'prefer-canonical-length-constrained-tuple':
     preferCanonicalLengthConstrainedTuple,
+  'prefer-canonical-mutable-record': preferCanonicalMutableRecord,
   'prefer-readonly-or-mutable-record': preferReadonlyOrMutableRecord,
   'prefer-strict-or-relaxed-utility-type': preferStrictOrRelaxedUtilityType,
 } as const satisfies ESLintPlugin['rules'];

package/src/rules/std-type-rule-utils.mts

@@ -1,10 +1,10 @@
 import {
   AST_NODE_TYPES,
-  ASTUtils,
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
 import { Arr } from 'ts-data-forge';
+import { isLocallyBound } from './ast-utils.mjs';
 import { resolveTypeName, type ImportStyle } from './import-style.mjs';
 import { buildTypeImportFix } from './import-utils.mjs';
 
@@ -81,23 +81,3 @@ export const reportStdTypeReference = <MessageIds extends string>(
 /** `['StrictPick', 'RelaxedPick']` → `` '`StrictPick` or `RelaxedPick`' ``. */
 const formatAlternatives = (candidates: readonly string[]): string =>
   candidates.map((candidate) => `\`${candidate}\``).join(' or ');
-
-/**
- * Whether `name` resolves to a declaration in this file (a type alias, an
- * interface, a class, an import, …) rather than to the ambient standard-library
- * type of the same name.
- *
- * The `defs` check is what separates the two: ESLint materializes an *implicit*
- * global variable for every unresolved reference, so `findVariable` also
- * succeeds for `Exclude` in a file that never declares it. Only a variable with
- * at least one definition was actually written down somewhere in this file.
- */
-const isLocallyBound = (
-  sourceCode: TSESLint.SourceCode,
-  node: TSESTree.Node,
-  name: string,
-): boolean => {
-  const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
-
-  return variable !== null && Arr.isNonEmpty(variable.defs);
-};

package/dist/rules/tuple-rule-utils.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tuple-rule-utils.d.mts","sourceRoot":"","sources":["../../src/rules/tuple-rule-utils.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKvE,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,SAAS,MAAM,WAClD,QAAQ,CAAC,WAAW,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC,YACnD,SAAS,YAAY,EAAE,aACtB,UAAU,eACR,WAAW,KACvB,IAuCF,CAAC"}

package/dist/rules/tuple-rule-utils.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"tuple-rule-utils.mjs","sources":["../../src/rules/tuple-rule-utils.mts"],"sourcesContent":["import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';\nimport { Arr } from 'ts-data-forge';\nimport { resolveTypeName, type ImportStyle } from './import-style.mjs';\nimport { buildTypeImportFix } from './import-utils.mjs';\n\n/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */\n\nexport type TupleRewrite = Readonly<{\n  node: TSESTree.Node;\n  canonicalName: string;\n  /** Text inside the `<...>` of the replacement, e.g. `'2, string'`. */\n  typeArgs: string;\n}>;\n\n/**\n * Emits one report per rewrite, resolving each target name and attaching every\n * required import to the *first* report.\n *\n * All import fixes must live on a single report: `insertTextBefore(program, …)`\n * produces overlapping ranges, and ESLint merges each report's fixes into one\n * span — so spreading them across reports makes the fixes conflict and only one\n * survives per pass.\n */\nexport const reportTupleRewrites = <MessageIds extends string>(\n  context: TSESLint.RuleContext<MessageIds, readonly unknown[]>,\n  rewrites: readonly TupleRewrite[],\n  messageId: MessageIds,\n  importStyle: ImportStyle,\n): void => {\n  const sourceCode = context.sourceCode;\n\n  const program = sourceCode.ast;\n\n  const resolved = rewrites.flatMap((rewrite) => {\n    const target = resolveTypeName(program, rewrite.canonicalName, importStyle);\n\n    // The name is already bound to something else in this file, so the rewrite\n    // would resolve to the wrong declaration.\n    return target === undefined ? [] : [{ rewrite, target }];\n  });\n\n  const importNames = Array.from(\n    new Set(\n      resolved\n        .filter(({ target }) => target.needsImport)\n        .map(({ rewrite }) => rewrite.canonicalName),\n    ),\n  );\n\n  for (const [index, { rewrite, target }] of resolved.entries()) {\n    const replacement = `${target.localName}<${rewrite.typeArgs}>`;\n\n    context.report({\n      node: rewrite.node,\n      messageId,\n      data: { original: sourceCode.getText(rewrite.node), replacement },\n      fix: (fixer) =>\n        Arr.toPushed(\n          index === 0\n            ? importNames.flatMap((name) =>\n                buildTypeImportFix(fixer, program, name),\n              )\n            : [],\n          fixer.replaceText(rewrite.node, replacement),\n        ),\n    });\n  }\n};\n"],"names":[],"mappings":";;;;AAuBO,MAAM,mBAAA,GAAsB,CACjC,OAAA,EACA,QAAA,EACA,WACA,WAAA,KACS;AACT,EAAA,MAAM,aAAa,OAAA,CAAQ,UAAA;AAE3B,EAAA,MAAM,UAAU,UAAA,CAAW,GAAA;AAE3B,EAAA,MAAM,QAAA,GAAW,QAAA,CAAS,OAAA,CAAQ,CAAC,OAAA,KAAY;AAC7C,IAAA,MAAM,MAAA,GAAS,eAAA,CAAgB,OAAA,EAAS,OAAA,CAAQ,eAAe,WAAW,CAAA;AAI1E,IAAA,OAAO,MAAA,KAAW,SAAY,EAAC,GAAI,CAAC,EAAE,OAAA,EAAS,QAAQ,CAAA;AAAA,EACzD,CAAC,CAAA;AAED,EAAA,MAAM,cAAc,KAAA,CAAM,IAAA;AAAA,IACxB,IAAI,GAAA;AAAA,MACF,QAAA,CACG,MAAA,CAAO,CAAC,EAAE,QAAO,KAAM,MAAA,CAAO,WAAW,CAAA,CACzC,IAAI,CAAC,EAAE,OAAA,EAAQ,KAAM,QAAQ,aAAa;AAAA;AAC/C,GACF;AAEA,EAAA,KAAA,MAAW,CAAC,OAAO,EAAE,OAAA,EAAS,QAAQ,CAAA,IAAK,QAAA,CAAS,OAAA,EAAQ,EAAG;AAC7D,IAAA,MAAM,cAAc,CAAA,EAAG,MAAA,CAAO,SAAS,CAAA,CAAA,EAAI,QAAQ,QAAQ,CAAA,CAAA,CAAA;AAE3D,IAAA,OAAA,CAAQ,MAAA,CAAO;AAAA,MACb,MAAM,OAAA,CAAQ,IAAA;AAAA,MACd,SAAA;AAAA,MACA,IAAA,EAAM,EAAE,QAAA,EAAU,UAAA,CAAW,QAAQ,OAAA,CAAQ,IAAI,GAAG,WAAA,EAAY;AAAA,MAChE,GAAA,EAAK,CAAC,KAAA,KACJ,GAAA,CAAI,QAAA;AAAA,QACF,KAAA,KAAU,IACN,WAAA,CAAY,OAAA;AAAA,UAAQ,CAAC,IAAA,KACnB,kBAAA,CAAmB,KAAA,EAAO,SAAS,IAAI;AAAA,YAEzC,EAAC;AAAA,QACL,KAAA,CAAM,WAAA,CAAY,OAAA,CAAQ,IAAA,EAAM,WAAW;AAAA;AAC7C,KACH,CAAA;AAAA,EACH;AACF;;;;"}