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

package/dist/rules/std-type-rule-utils.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"std-type-rule-utils.d.mts","sourceRoot":"","sources":["../../src/rules/std-type-rule-utils.mts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKvE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAEzE;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAU,SAAS,MAAM,WACrD,QAAQ,CAAC,WAAW,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC,QACvD,QAAQ,CAAC,eAAe,gBAChB,mBAAmB,cACrB,QAAQ,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,eACvD,WAAW,KACvB,IA4CF,CAAC"}
+{"version":3,"file":"std-type-rule-utils.d.mts","sourceRoot":"","sources":["../../src/rules/std-type-rule-utils.mts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKvE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAEzE;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAU,SAAS,MAAM,WACrD,QAAQ,CAAC,WAAW,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC,QACvD,QAAQ,CAAC,eAAe,gBAChB,mBAAmB,cACrB,QAAQ,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,eACvD,WAAW,KACvB,IA4CF,CAAC"}

package/dist/rules/std-type-rule-utils.mjs

@@ -1,5 +1,6 @@
-import { AST_NODE_TYPES, ASTUtils } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
 import { Arr } from 'ts-data-forge';
+import { isLocallyBound } from './ast-utils.mjs';
 import { resolveTypeName } from './import-style.mjs';
 import { buildTypeImportFix } from './import-utils.mjs';
 
@@ -31,10 +32,6 @@ const reportStdTypeReference = (context, node, alternatives, messageIds, importS
   });
 };
 const formatAlternatives = (candidates) => candidates.map((candidate) => `\`${candidate}\``).join(" or ");
-const isLocallyBound = (sourceCode, node, name) => {
-  const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
-  return variable !== null && Arr.isNonEmpty(variable.defs);
-};
 
 export { reportStdTypeReference };
 //# sourceMappingURL=std-type-rule-utils.mjs.map

package/dist/rules/std-type-rule-utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"std-type-rule-utils.mjs","sources":["../../src/rules/std-type-rule-utils.mts"],"sourcesContent":["import {\n  AST_NODE_TYPES,\n  ASTUtils,\n  type TSESLint,\n  type TSESTree,\n} 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\n/**\n * The ts-type-forge replacements offered for one standard-library type, in the\n * order they are suggested.\n */\nexport type StdTypeAlternatives = ReadonlyMap<string, readonly string[]>;\n\n/**\n * Reports a reference to a banned standard-library type and offers one\n * suggestion per ts-type-forge alternative.\n *\n * Choosing between the alternatives is a semantic decision — `StrictExclude`\n * additionally checks that the subtrahend is part of the union, `ReadonlyRecord`\n * and `MutableRecord` describe different types — so this is deliberately *not*\n * an autofix. Each suggestion carries its own import fix, which is safe because\n * ESLint applies suggestions one at a time.\n */\nexport const reportStdTypeReference = <MessageIds extends string>(\n  context: TSESLint.RuleContext<MessageIds, readonly unknown[]>,\n  node: TSESTree.TSTypeReference,\n  alternatives: StdTypeAlternatives,\n  messageIds: Readonly<{ report: MessageIds; suggestion: MessageIds }>,\n  importStyle: ImportStyle,\n): void => {\n  const typeName = node.typeName;\n\n  // `ns.Pick` / `import('…').Pick` never denote the standard-library type.\n  if (typeName.type !== AST_NODE_TYPES.Identifier) return;\n\n  const stdName = typeName.name;\n\n  const candidates = alternatives.get(stdName);\n\n  if (candidates === undefined) return;\n\n  // A file that declares — or imports — its own `Pick` does not mean the\n  // standard-library one, so there is nothing to steer.\n  if (isLocallyBound(context.sourceCode, node, stdName)) return;\n\n  const program = context.sourceCode.ast;\n\n  context.report({\n    node: typeName,\n    messageId: messageIds.report,\n    data: { name: stdName, alternatives: formatAlternatives(candidates) },\n    suggest: candidates.flatMap((candidate) => {\n      const target = resolveTypeName(program, candidate, importStyle);\n\n      // The replacement name is already bound to something else in this file,\n      // so rewriting to it would resolve to the wrong declaration.\n      return target === undefined\n        ? []\n        : [\n            {\n              messageId: messageIds.suggestion,\n              data: { name: stdName, replacement: target.localName },\n              fix: (fixer: TSESLint.RuleFixer): readonly TSESLint.RuleFix[] =>\n                Arr.toPushed(\n                  target.needsImport\n                    ? buildTypeImportFix(fixer, program, candidate)\n                    : [],\n                  fixer.replaceText(typeName, target.localName),\n                ),\n            },\n          ];\n    }),\n  });\n};\n\n/** `['StrictPick', 'RelaxedPick']` → `` '`StrictPick` or `RelaxedPick`' ``. */\nconst formatAlternatives = (candidates: readonly string[]): string =>\n  candidates.map((candidate) => `\\`${candidate}\\``).join(' or ');\n\n/**\n * Whether `name` resolves to a declaration in this file (a type alias, an\n * interface, a class, an import, …) rather than to the ambient standard-library\n * type of the same name.\n *\n * The `defs` check is what separates the two: ESLint materializes an *implicit*\n * global variable for every unresolved reference, so `findVariable` also\n * succeeds for `Exclude` in a file that never declares it. Only a variable with\n * at least one definition was actually written down somewhere in this file.\n */\nconst isLocallyBound = (\n  sourceCode: TSESLint.SourceCode,\n  node: TSESTree.Node,\n  name: string,\n): boolean => {\n  const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);\n\n  return variable !== null && Arr.isNonEmpty(variable.defs);\n};\n"],"names":[],"mappings":";;;;;AA4BO,MAAM,yBAAyB,CACpC,OAAA,EACA,IAAA,EACA,YAAA,EACA,YACA,WAAA,KACS;AACT,EAAA,MAAM,WAAW,IAAA,CAAK,QAAA;AAGtB,EAAA,IAAI,QAAA,CAAS,IAAA,KAAS,cAAA,CAAe,UAAA,EAAY;AAEjD,EAAA,MAAM,UAAU,QAAA,CAAS,IAAA;AAEzB,EAAA,MAAM,UAAA,GAAa,YAAA,CAAa,GAAA,CAAI,OAAO,CAAA;AAE3C,EAAA,IAAI,eAAe,MAAA,EAAW;AAI9B,EAAA,IAAI,cAAA,CAAe,OAAA,CAAQ,UAAA,EAAY,IAAA,EAAM,OAAO,CAAA,EAAG;AAEvD,EAAA,MAAM,OAAA,GAAU,QAAQ,UAAA,CAAW,GAAA;AAEnC,EAAA,OAAA,CAAQ,MAAA,CAAO;AAAA,IACb,IAAA,EAAM,QAAA;AAAA,IACN,WAAW,UAAA,CAAW,MAAA;AAAA,IACtB,MAAM,EAAE,IAAA,EAAM,SAAS,YAAA,EAAc,kBAAA,CAAmB,UAAU,CAAA,EAAE;AAAA,IACpE,OAAA,EAAS,UAAA,CAAW,OAAA,CAAQ,CAAC,SAAA,KAAc;AACzC,MAAA,MAAM,MAAA,GAAS,eAAA,CAAgB,OAAA,EAAS,SAAA,EAAW,WAAW,CAAA;AAI9D,MAAA,OAAO,MAAA,KAAW,MAAA,GACd,EAAC,GACD;AAAA,QACE;AAAA,UACE,WAAW,UAAA,CAAW,UAAA;AAAA,UACtB,MAAM,EAAE,IAAA,EAAM,OAAA,EAAS,WAAA,EAAa,OAAO,SAAA,EAAU;AAAA,UACrD,GAAA,EAAK,CAAC,KAAA,KACJ,GAAA,CAAI,QAAA;AAAA,YACF,OAAO,WAAA,GACH,kBAAA,CAAmB,OAAO,OAAA,EAAS,SAAS,IAC5C,EAAC;AAAA,YACL,KAAA,CAAM,WAAA,CAAY,QAAA,EAAU,MAAA,CAAO,SAAS;AAAA;AAC9C;AACJ,OACF;AAAA,IACN,CAAC;AAAA,GACF,CAAA;AACH;AAGA,MAAM,kBAAA,GAAqB,CAAC,UAAA,KAC1B,UAAA,CAAW,GAAA,CAAI,CAAC,SAAA,KAAc,CAAA,EAAA,EAAK,SAAS,CAAA,EAAA,CAAI,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAY/D,MAAM,cAAA,GAAiB,CACrB,UAAA,EACA,IAAA,EACA,IAAA,KACY;AACZ,EAAA,MAAM,WAAW,QAAA,CAAS,YAAA,CAAa,WAAW,QAAA,CAAS,IAAI,GAAG,IAAI,CAAA;AAEtE,EAAA,OAAO,QAAA,KAAa,IAAA,IAAQ,GAAA,CAAI,UAAA,CAAW,SAAS,IAAI,CAAA;AAC1D,CAAA;;;;"}
+{"version":3,"file":"std-type-rule-utils.mjs","sources":["../../src/rules/std-type-rule-utils.mts"],"sourcesContent":["import {\n  AST_NODE_TYPES,\n  type TSESLint,\n  type TSESTree,\n} from '@typescript-eslint/utils';\nimport { Arr } from 'ts-data-forge';\nimport { isLocallyBound } from './ast-utils.mjs';\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\n/**\n * The ts-type-forge replacements offered for one standard-library type, in the\n * order they are suggested.\n */\nexport type StdTypeAlternatives = ReadonlyMap<string, readonly string[]>;\n\n/**\n * Reports a reference to a banned standard-library type and offers one\n * suggestion per ts-type-forge alternative.\n *\n * Choosing between the alternatives is a semantic decision — `StrictExclude`\n * additionally checks that the subtrahend is part of the union, `ReadonlyRecord`\n * and `MutableRecord` describe different types — so this is deliberately *not*\n * an autofix. Each suggestion carries its own import fix, which is safe because\n * ESLint applies suggestions one at a time.\n */\nexport const reportStdTypeReference = <MessageIds extends string>(\n  context: TSESLint.RuleContext<MessageIds, readonly unknown[]>,\n  node: TSESTree.TSTypeReference,\n  alternatives: StdTypeAlternatives,\n  messageIds: Readonly<{ report: MessageIds; suggestion: MessageIds }>,\n  importStyle: ImportStyle,\n): void => {\n  const typeName = node.typeName;\n\n  // `ns.Pick` / `import('…').Pick` never denote the standard-library type.\n  if (typeName.type !== AST_NODE_TYPES.Identifier) return;\n\n  const stdName = typeName.name;\n\n  const candidates = alternatives.get(stdName);\n\n  if (candidates === undefined) return;\n\n  // A file that declares — or imports — its own `Pick` does not mean the\n  // standard-library one, so there is nothing to steer.\n  if (isLocallyBound(context.sourceCode, node, stdName)) return;\n\n  const program = context.sourceCode.ast;\n\n  context.report({\n    node: typeName,\n    messageId: messageIds.report,\n    data: { name: stdName, alternatives: formatAlternatives(candidates) },\n    suggest: candidates.flatMap((candidate) => {\n      const target = resolveTypeName(program, candidate, importStyle);\n\n      // The replacement name is already bound to something else in this file,\n      // so rewriting to it would resolve to the wrong declaration.\n      return target === undefined\n        ? []\n        : [\n            {\n              messageId: messageIds.suggestion,\n              data: { name: stdName, replacement: target.localName },\n              fix: (fixer: TSESLint.RuleFixer): readonly TSESLint.RuleFix[] =>\n                Arr.toPushed(\n                  target.needsImport\n                    ? buildTypeImportFix(fixer, program, candidate)\n                    : [],\n                  fixer.replaceText(typeName, target.localName),\n                ),\n            },\n          ];\n    }),\n  });\n};\n\n/** `['StrictPick', 'RelaxedPick']` → `` '`StrictPick` or `RelaxedPick`' ``. */\nconst formatAlternatives = (candidates: readonly string[]): string =>\n  candidates.map((candidate) => `\\`${candidate}\\``).join(' or ');\n"],"names":[],"mappings":";;;;;;AA4BO,MAAM,yBAAyB,CACpC,OAAA,EACA,IAAA,EACA,YAAA,EACA,YACA,WAAA,KACS;AACT,EAAA,MAAM,WAAW,IAAA,CAAK,QAAA;AAGtB,EAAA,IAAI,QAAA,CAAS,IAAA,KAAS,cAAA,CAAe,UAAA,EAAY;AAEjD,EAAA,MAAM,UAAU,QAAA,CAAS,IAAA;AAEzB,EAAA,MAAM,UAAA,GAAa,YAAA,CAAa,GAAA,CAAI,OAAO,CAAA;AAE3C,EAAA,IAAI,eAAe,MAAA,EAAW;AAI9B,EAAA,IAAI,cAAA,CAAe,OAAA,CAAQ,UAAA,EAAY,IAAA,EAAM,OAAO,CAAA,EAAG;AAEvD,EAAA,MAAM,OAAA,GAAU,QAAQ,UAAA,CAAW,GAAA;AAEnC,EAAA,OAAA,CAAQ,MAAA,CAAO;AAAA,IACb,IAAA,EAAM,QAAA;AAAA,IACN,WAAW,UAAA,CAAW,MAAA;AAAA,IACtB,MAAM,EAAE,IAAA,EAAM,SAAS,YAAA,EAAc,kBAAA,CAAmB,UAAU,CAAA,EAAE;AAAA,IACpE,OAAA,EAAS,UAAA,CAAW,OAAA,CAAQ,CAAC,SAAA,KAAc;AACzC,MAAA,MAAM,MAAA,GAAS,eAAA,CAAgB,OAAA,EAAS,SAAA,EAAW,WAAW,CAAA;AAI9D,MAAA,OAAO,MAAA,KAAW,MAAA,GACd,EAAC,GACD;AAAA,QACE;AAAA,UACE,WAAW,UAAA,CAAW,UAAA;AAAA,UACtB,MAAM,EAAE,IAAA,EAAM,OAAA,EAAS,WAAA,EAAa,OAAO,SAAA,EAAU;AAAA,UACrD,GAAA,EAAK,CAAC,KAAA,KACJ,GAAA,CAAI,QAAA;AAAA,YACF,OAAO,WAAA,GACH,kBAAA,CAAmB,OAAO,OAAA,EAAS,SAAS,IAC5C,EAAC;AAAA,YACL,KAAA,CAAM,WAAA,CAAY,QAAA,EAAU,MAAA,CAAO,SAAS;AAAA;AAC9C;AACJ,OACF;AAAA,IACN,CAAC;AAAA,GACF,CAAA;AACH;AAGA,MAAM,kBAAA,GAAqB,CAAC,UAAA,KAC1B,UAAA,CAAW,GAAA,CAAI,CAAC,SAAA,KAAc,CAAA,EAAA,EAAK,SAAS,CAAA,EAAA,CAAI,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-ts-type-forge",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "private": false,
   "description": "ESLint rules that steer type declarations toward ts-type-forge idioms.",
   "keywords": [
@@ -37,20 +37,20 @@
   "dependencies": {
     "@typescript-eslint/utils": "~8.67.0",
     "ts-data-forge": "~14.4.0",
-    "ts-type-forge": "9.2.1"
+    "ts-type-forge": "9.2.2"
   },
   "devDependencies": {
     "@typescript-eslint/parser": "8.67.0",
     "@typescript-eslint/rule-tester": "8.67.0",
     "dedent": "1.7.2",
+    "eslint-config-typed": "5.9.5",
+    "eslint-plugin-ts-data-forge": "0.5.0",
+    "eslint-plugin-ts-fortress": "1.0.4",
     "prettier": "3.9.6",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
     "rollup": "4.62.4",
-    "eslint-config-typed": "5.9.3",
-    "eslint-plugin-ts-data-forge": "0.4.8",
-    "eslint-plugin-ts-fortress": "1.0.4",
-    "ts-repo-utils": "10.2.0"
+    "ts-repo-utils": "10.3.2"
   },
   "peerDependencies": {
     "eslint": ">=9.0.0",

package/src/plugin.mts

@@ -9,6 +9,7 @@ import { type ESLintFlatConfig, type ESLintPlugin } from './types.mjs';
  */
 const recommendedRules = {
   'ts-type-forge/prefer-canonical-length-constrained-tuple': 'error',
+  'ts-type-forge/prefer-canonical-mutable-record': 'error',
   'ts-type-forge/prefer-readonly-or-mutable-record': 'error',
   'ts-type-forge/prefer-strict-or-relaxed-utility-type': 'error',
 } as const satisfies Readonly<

package/src/rule-types.mts

@@ -76,6 +76,50 @@ namespace PreferCanonicalLengthConstrainedTuple {
     | SpreadOptionsIfIsArray<readonly [Linter.StringSeverity, Options]>;
 }
 
+/**
+ * @description Replace `Mutable<Record<K, V>>` (and `Mutable` applied to `ReadonlyRecord` / `MutableRecord`) with the canonical ts-type-forge `MutableRecord<K, V>`.
+ *
+ *  ```md
+ *  | key        | value      |
+ *  | :--------- | :--------- |
+ *  | type       | suggestion |
+ *  | deprecated | false      |
+ *  | fixable    | code       |
+ *  ```
+ */
+namespace PreferCanonicalMutableRecord {
+  /**
+   * ### schema
+   *
+   * ```json
+   * [
+   *   {
+   *     "type": "object",
+   *     "properties": {
+   *       "importStyle": {
+   *         "type": "string",
+   *         "enum": [
+   *           "global",
+   *           "named"
+   *         ],
+   *         "description": "How the ts-type-forge type is brought into scope. 'named' (default) makes the autofix add the corresponding `import { type … } from 'ts-type-forge';` when the name is not imported yet; 'global' assumes the ambient globals of `ts-type-forge/global` and never touches imports."
+   *       }
+   *     },
+   *     "additionalProperties": false
+   *   }
+   * ]
+   * ```
+   */
+  export type Options = NonNullable<
+    RuleOptionsOf<'prefer-canonical-mutable-record'>[0]
+  >;
+
+  export type RuleEntry =
+    | 'off'
+    | Linter.Severity
+    | SpreadOptionsIfIsArray<readonly [Linter.StringSeverity, Options]>;
+}
+
 /**
  * @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.
  *
@@ -166,12 +210,14 @@ namespace PreferStrictOrRelaxedUtilityType {
 
 export type EslintTsTypeForgeRules = Readonly<{
   'ts-type-forge/prefer-canonical-length-constrained-tuple': PreferCanonicalLengthConstrainedTuple.RuleEntry;
+  'ts-type-forge/prefer-canonical-mutable-record': PreferCanonicalMutableRecord.RuleEntry;
   'ts-type-forge/prefer-readonly-or-mutable-record': PreferReadonlyOrMutableRecord.RuleEntry;
   'ts-type-forge/prefer-strict-or-relaxed-utility-type': PreferStrictOrRelaxedUtilityType.RuleEntry;
 }>;
 
 export type EslintTsTypeForgeRulesOption = Readonly<{
   'ts-type-forge/prefer-canonical-length-constrained-tuple': PreferCanonicalLengthConstrainedTuple.Options;
+  'ts-type-forge/prefer-canonical-mutable-record': PreferCanonicalMutableRecord.Options;
   'ts-type-forge/prefer-readonly-or-mutable-record': PreferReadonlyOrMutableRecord.Options;
   'ts-type-forge/prefer-strict-or-relaxed-utility-type': PreferStrictOrRelaxedUtilityType.Options;
 }>;

package/src/rules/ast-utils.mts

@@ -1,12 +1,33 @@
 import {
   AST_NODE_TYPES,
+  ASTUtils,
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { Arr } from 'ts-data-forge';
+import { Arr, hasKey, isNonNullObject, isRecord } from 'ts-data-forge';
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
 
+/**
+ * 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.
+ */
+export 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);
+};
+
 export type UniformTupleShape = Readonly<{
   /** The node an autofix must replace: the tuple, or the `readonly` operator. */
   node: TSESTree.Node;
@@ -91,17 +112,24 @@ export const analyzeUniformTuple = (
     ...(restElementType === undefined ? [] : [restElementType]),
   ];
 
-  return others.every(
-    (element) => normalizeWhitespace(sourceCode.getText(element)) === expected,
-  )
-    ? {
+  if (
+    others.some(
+      (element) =>
+        normalizeWhitespace(sourceCode.getText(element)) !== expected,
+    )
+  ) {
+    return undefined;
+  }
+
+  return definesRecursiveTypeAlias(tuple, sourceCode)
+    ? undefined
+    : {
         node: isReadonly ? parent : tuple,
         isReadonly,
         elementText,
         fixedCount: leading.length,
         hasRest,
-      }
-    : undefined;
+      };
 };
 
 /**
@@ -128,6 +156,188 @@ const isInConditionalTypeExtendsClause = (node: TSESTree.Node): boolean => {
   );
 };
 
+/**
+ * Whether the tuple spells out an alias that its own element type leads back
+ * to.
+ *
+ * A tuple literal is how TypeScript's cycle-breaking works: `type T = readonly
+ * [T, T]` resolves, because the element positions are deferred. Rewriting it to
+ * `FixedLengthTuple<2, T>` routes the same cycle through a mapped type, which
+ * the checker will not compute — `T` becomes an error type, and every use of it
+ * silently reads as `any`. `tsc` reports the alias once; the typed linter then
+ * reports each use, which is how this was found.
+ *
+ * The cycle is often indirect. `LambdaApplication = readonly [LambdaTerm,
+ * LambdaTerm]` looks fine on its own, and only recurses because `LambdaTerm` is
+ * a union that includes `LambdaApplication`. So this follows references through
+ * the other aliases in the file rather than looking for the enclosing name in
+ * the element text.
+ *
+ * **Any cycle counts, which leaves some rewritable tuples alone.** Not every
+ * cycle actually breaks: TypeScript resolves an object type, an array, a tuple
+ * and a function type without resolving what is inside them, so `type Pair =
+ * FixedLengthTuple<2, Foo>` alongside `type Foo = { p: Pair }` compiles, and so
+ * does `type Tree = { kids: FixedLengthTuple<2, Tree> }`. Skipping those
+ * constructs while following references was tried and does not hold up — the
+ * deferral is undone by anything that asks for the structure, and that can sit
+ * anywhere in the file:
+ *
+ * ```ts
+ * type Pair = readonly [Foo, Foo]; // rewriting this breaks Pair and Foo
+ * type Foo = Wrapper[number]; // …because of the indexed access here
+ * type Wrapper = readonly Pair[];
+ * ```
+ *
+ * Deciding it properly means knowing every use of every alias, which no
+ * syntactic rule can do — so a cycle of any shape suppresses the rewrite. The
+ * cost is a tuple left spelled out; the alternative is an autofix that turns a
+ * type into `any`.
+ *
+ * A cycle closed through an `import` is not visible here and is not detected.
+ */
+const definesRecursiveTypeAlias = (
+  tuple: TSESTree.TSTupleType,
+  sourceCode: TSESLint.SourceCode,
+): boolean => {
+  const alias = enclosingTypeAlias(tuple);
+
+  if (alias === undefined) return false;
+
+  const references = aliasReferenceGraph(programOf(alias), sourceCode);
+
+  const mut_seen = new Set<string>();
+
+  const mut_queue: string[] = tuple.elementTypes.flatMap((element) =>
+    Array.from(referencedTypeNames(element, sourceCode)),
+  );
+
+  while (true) {
+    const next = mut_queue.pop();
+
+    if (next === undefined) return false;
+
+    if (next === alias.id.name) return true;
+
+    if (mut_seen.has(next)) continue;
+
+    mut_seen.add(next);
+
+    const referenced = references.get(next);
+
+    if (referenced !== undefined) {
+      mut_queue.push(...referenced);
+    }
+  }
+};
+
+/** The `type X = …` declaration `node` sits in, if any. */
+const enclosingTypeAlias = (
+  node: TSESTree.Node,
+): TSESTree.TSTypeAliasDeclaration | undefined => {
+  if (node.type === AST_NODE_TYPES.TSTypeAliasDeclaration) return node;
+
+  if (node.type === AST_NODE_TYPES.Program) return undefined;
+
+  return enclosingTypeAlias(node.parent);
+};
+
+/**
+ * Which other type names each `type X = …` in the file refers to, keyed by `X`.
+ *
+ * Built once per file and cached on the `Program` node: the search below runs
+ * per candidate tuple, and rebuilding this for each of them made the rule cost
+ * `O(tuples × file size)` — a full second on the largest generated files here.
+ */
+const aliasReferenceGraph = (
+  program: TSESTree.Program,
+  sourceCode: TSESLint.SourceCode,
+): ReadonlyMap<string, ReadonlySet<string>> => {
+  const cached = aliasReferenceGraphCache.get(program);
+
+  if (cached !== undefined) return cached;
+
+  const mut_graph = new Map<string, ReadonlySet<string>>();
+
+  walk(program, sourceCode, (visited) => {
+    if (visited.type === AST_NODE_TYPES.TSTypeAliasDeclaration) {
+      mut_graph.set(
+        visited.id.name,
+        referencedTypeNames(visited.typeAnnotation, sourceCode),
+      );
+    }
+  });
+
+  aliasReferenceGraphCache.set(program, mut_graph);
+
+  return mut_graph;
+};
+
+const aliasReferenceGraphCache = new WeakMap<
+  TSESTree.Program,
+  ReadonlyMap<string, ReadonlySet<string>>
+>();
+
+const programOf = (node: TSESTree.Node): TSESTree.Program =>
+  node.type === AST_NODE_TYPES.Program ? node : programOf(node.parent);
+
+/** The names every `X` / `X<…>` reference in the subtree points at. */
+const referencedTypeNames = (
+  node: TSESTree.Node,
+  sourceCode: TSESLint.SourceCode,
+): ReadonlySet<string> => {
+  const mut_names = new Set<string>();
+
+  walk(node, sourceCode, (visited) => {
+    if (
+      visited.type === AST_NODE_TYPES.TSTypeReference &&
+      visited.typeName.type === AST_NODE_TYPES.Identifier
+    ) {
+      mut_names.add(visited.typeName.name);
+    }
+  });
+
+  return mut_names;
+};
+
+/**
+ * Visits `node` and its descendants.
+ *
+ * Children are found through the parser's visitor keys, so only the properties
+ * that actually hold one are read. Reading every own property instead works
+ * too, and is the fallback for a parser that declares no keys for a node type,
+ * but it allocates an entry pair per property and walks `loc` / `range` as
+ * well — on the generated rule-type files that alone was most of the cost.
+ */
+const walk = (
+  node: TSESTree.Node,
+  sourceCode: TSESLint.SourceCode,
+  visit: (visited: TSESTree.Node) => void,
+): void => {
+  visit(node);
+
+  if (!isRecord(node)) return;
+
+  const keys =
+    sourceCode.visitorKeys[node.type] ??
+    Object.keys(node).filter((key) => key !== 'parent');
+
+  for (const key of keys) {
+    const value: unknown = hasKey(node, key) ? node[key] : undefined;
+
+    if (Arr.isArray(value)) {
+      for (const element of value) {
+        if (isNode(element)) walk(element, sourceCode, visit);
+      }
+    } else if (isNode(value)) {
+      walk(value, sourceCode, visit);
+    }
+  }
+};
+
+const isNode = (value: unknown): value is TSESTree.Node =>
+  isNonNullObject(value) &&
+  typeof (value as Readonly<{ type?: unknown }>).type === 'string';
+
 /** Unwraps `V[]` and `readonly V[]` to `V`. */
 const getArrayElementType = (
   node: TSESTree.TypeNode,

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

@@ -13,7 +13,7 @@ import {
   DEFAULT_IMPORT_STYLE,
   IMPORT_STYLE_SCHEMA_PROPERTY,
 } from './import-style.mjs';
-import { reportTupleRewrites, type TupleRewrite } from './tuple-rule-utils.mjs';
+import { reportTypeRewrites, type TypeRewrite } from './rewrite-rule-utils.mjs';
 
 type Options = readonly [
   Readonly<{
@@ -75,7 +75,7 @@ export const preferCanonicalLengthConstrainedTuple: TSESLint.RuleModule<
 
     const maxLength = options?.maxLength ?? DEFAULT_MAX_TUPLE_LENGTH;
 
-    const mut_rewrites: TupleRewrite[] = [];
+    const mut_rewrites: TypeRewrite[] = [];
 
     return {
       TSTupleType: (node) => {
@@ -97,7 +97,7 @@ export const preferCanonicalLengthConstrainedTuple: TSESLint.RuleModule<
         });
       },
       'Program:exit': () => {
-        reportTupleRewrites(
+        reportTypeRewrites(
           context,
           mut_rewrites,
           'useCanonicalTuple',

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

@@ -41,6 +41,77 @@ describe('prefer-canonical-length-constrained-tuple', () => {
           name: 'ignores rest-only tuples',
           code: 'type T = readonly [...string[]];',
         },
+        {
+          name: 'ignores a tuple that defines a directly recursive alias',
+          code: 'type T = readonly [T, T];',
+        },
+        {
+          name: 'ignores a tuple whose alias recurses through another alias',
+          code: dedent`
+            type LambdaTerm = string | LambdaApplication;
+            type LambdaApplication = readonly [LambdaTerm, LambdaTerm];
+          `,
+        },
+        {
+          name: 'ignores a tuple whose alias recurses through a chain of aliases',
+          code: dedent`
+            type A = readonly [B, B];
+            type B = C;
+            type C = A | string;
+          `,
+        },
+        {
+          name: 'ignores a tuple whose alias recurses through an intersection',
+          code: dedent`
+            type Pair = readonly [Foo, Foo];
+            type Foo = Pair & { readonly tag: string };
+          `,
+        },
+        {
+          name: 'ignores a tuple whose alias recurses through a type argument',
+          code: dedent`
+            type Pair = readonly [Box<Pair>, Box<Pair>];
+            type Box<T> = { readonly v: T };
+          `,
+        },
+        {
+          name: 'ignores a tuple whose alias recurses through an indexed access',
+          code: dedent`
+            type Pair = readonly [Foo, Foo];
+            type Foo = Wrapper[number];
+            type Wrapper = readonly Pair[];
+          `,
+        },
+        {
+          // Both of these compile either way: TypeScript resolves an object
+          // type without resolving its members, so the rewritten form is fine
+          // here. The rule suppresses them all the same — see the note on
+          // `definesRecursiveTypeAlias` for why the exception cannot be made
+          // safely.
+          name: 'conservatively ignores a cycle closed through an object type',
+          code: dedent`
+            type Pair = readonly [Foo, Foo];
+            type Foo = { readonly p: Pair };
+          `,
+        },
+        {
+          name: 'conservatively ignores a cycle closed through an array',
+          code: dedent`
+            type Pair = readonly [Foo, Foo];
+            type Foo = readonly Pair[];
+          `,
+        },
+        {
+          name: 'conservatively ignores a tuple nested in its own alias',
+          code: 'type Tree = { readonly kids: readonly [Tree, Tree] };',
+        },
+        {
+          name: 'still ignores nothing when the cycle does not reach the tuple',
+          code: dedent`
+            type Loop = readonly Loop[];
+            type Unrelated = string;
+          `,
+        },
         {
           name: 'ignores plain arrays',
           code: 'type T = readonly string[];',

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

@@ -0,0 +1,151 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { Arr } from 'ts-data-forge';
+import { isLocallyBound } from './ast-utils.mjs';
+import {
+  DEFAULT_IMPORT_STYLE,
+  IMPORT_STYLE_SCHEMA_PROPERTY,
+} from './import-style.mjs';
+import {
+  getImportedLocalName,
+  getTsTypeForgeImports,
+} from './import-utils.mjs';
+import { reportTypeRewrites, type TypeRewrite } from './rewrite-rule-utils.mjs';
+
+type Options = readonly [
+  Readonly<{
+    importStyle?: 'global' | 'named';
+  }>?,
+];
+
+type MessageIds = 'useMutableRecord';
+
+/**
+ * The record spellings that `Mutable<…>` collapses to `MutableRecord<K, V>`.
+ * `Mutable` strips the `readonly` modifier from every property, so applied to
+ * any of these it produces exactly the type `MutableRecord` spells directly.
+ */
+const WRAPPED_RECORD_NAMES = [
+  'Record',
+  'ReadonlyRecord',
+  'MutableRecord',
+] as const;
+
+const MUTABLE_TYPE_NAME = 'Mutable';
+
+const MUTABLE_RECORD_TYPE_NAME = 'MutableRecord';
+
+export const preferCanonicalMutableRecord: TSESLint.RuleModule<
+  MessageIds,
+  Options
+> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Replace `Mutable<Record<K, V>>` (and `Mutable` applied to `ReadonlyRecord` / `MutableRecord`) with the canonical ts-type-forge `MutableRecord<K, V>`.',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          importStyle: IMPORT_STYLE_SCHEMA_PROPERTY,
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      useMutableRecord:
+        'Replace `{{original}}` with `{{replacement}}` from ts-type-forge.',
+    },
+  },
+
+  create: (context) => {
+    const importStyle = context.options[0]?.importStyle ?? DEFAULT_IMPORT_STYLE;
+
+    const sourceCode = context.sourceCode;
+
+    const tsTypeForgeImports = getTsTypeForgeImports(sourceCode.ast);
+
+    /**
+     * Whether this reference denotes the ts-type-forge type `canonicalName` —
+     * either through an import from ts-type-forge (aliases included) or as the
+     * bare ambient global. A name bound to anything else in this file (a local
+     * alias, an import from another module) denotes that declaration instead.
+     * The built-in `Record` goes through the same check: ts-type-forge exports
+     * no `Record`, so only the unbound global spelling matches.
+     */
+    const referencesTsTypeForgeType = (
+      // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+      node: TSESTree.TSTypeReference,
+      canonicalName: string,
+    ): boolean => {
+      const typeName = node.typeName;
+
+      // `ns.Mutable` / `import('…').Mutable` never denote the ts-type-forge type.
+      if (typeName.type !== AST_NODE_TYPES.Identifier) return false;
+
+      return (
+        typeName.name ===
+          getImportedLocalName(tsTypeForgeImports, canonicalName) ||
+        (typeName.name === canonicalName &&
+          !isLocallyBound(sourceCode, node, canonicalName))
+      );
+    };
+
+    const mut_rewrites: TypeRewrite[] = [];
+
+    return {
+      TSTypeReference: (node) => {
+        if (!referencesTsTypeForgeType(node, MUTABLE_TYPE_NAME)) return;
+
+        const wrapped = node.typeArguments?.params;
+
+        if (wrapped === undefined || !Arr.isFixedLengthArray(1, wrapped)) {
+          return;
+        }
+
+        const record = wrapped[0];
+
+        if (
+          record.type !== AST_NODE_TYPES.TSTypeReference ||
+          WRAPPED_RECORD_NAMES.every(
+            (name) => !referencesTsTypeForgeType(record, name),
+          )
+        ) {
+          return;
+        }
+
+        const recordTypeArgs = record.typeArguments?.params;
+
+        if (
+          recordTypeArgs === undefined ||
+          !Arr.isFixedLengthArray(2, recordTypeArgs)
+        ) {
+          return;
+        }
+
+        const [K, V] = recordTypeArgs;
+
+        mut_rewrites.push({
+          node,
+          canonicalName: MUTABLE_RECORD_TYPE_NAME,
+          typeArgs: `${sourceCode.getText(K)}, ${sourceCode.getText(V)}`,
+        });
+      },
+      'Program:exit': () => {
+        reportTypeRewrites(
+          context,
+          mut_rewrites,
+          'useMutableRecord',
+          importStyle,
+        );
+      },
+    };
+  },
+  defaultOptions: [{ importStyle: DEFAULT_IMPORT_STYLE }],
+} as const;