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

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;

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

@@ -0,0 +1,279 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferStrictOrRelaxedUtilityType } from './prefer-strict-or-relaxed-utility-type.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+  },
+});
+
+describe('prefer-strict-or-relaxed-utility-type', () => {
+  tester.run(
+    'prefer-strict-or-relaxed-utility-type',
+    preferStrictOrRelaxedUtilityType,
+    {
+      valid: [
+        {
+          name: 'accepts the ts-type-forge counterparts',
+          code: dedent`
+            type A = StrictExclude<'a' | 'b', 'a'>;
+            type B = RelaxedExtract<string | number, number>;
+            type C = StrictOmit<{ a: 1; b: 2 }, 'a'>;
+            type D = RelaxedPick<{ a: 1; b: 2 }, 'a' | 'z'>;
+          `,
+        },
+        {
+          name: 'ignores unrelated standard-library types',
+          code: 'type A = Partial<Required<{ a: 1 }>>;',
+        },
+        {
+          name: 'ignores a qualified name that merely ends in a banned name',
+          code: "type A = Utils.Pick<{ a: 1 }, 'a'>;",
+        },
+        {
+          name: 'ignores a locally declared type of the same name',
+          code: dedent`
+            type Pick<T, K extends keyof T> = { readonly [P in K]: T[P] };
+            type A = Pick<{ a: 1 }, 'a'>;
+          `,
+        },
+        {
+          name: 'ignores a name imported from another module',
+          code: dedent`
+            import { type Omit } from './my-types.mjs';
+            type A = Omit<{ a: 1; b: 2 }, 'a'>;
+          `,
+        },
+      ],
+      invalid: [
+        {
+          name: 'reports `Exclude` and suggests both counterparts',
+          code: "type A = Exclude<'a' | 'b', 'a'>;",
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              data: {
+                name: 'Exclude',
+                alternatives: '`StrictExclude` or `RelaxedExclude`',
+              },
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Exclude', replacement: 'StrictExclude' },
+                  output: dedent`
+                    import { type StrictExclude } from 'ts-type-forge';
+                    type A = StrictExclude<'a' | 'b', 'a'>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Exclude', replacement: 'RelaxedExclude' },
+                  output: dedent`
+                    import { type RelaxedExclude } from 'ts-type-forge';
+                    type A = RelaxedExclude<'a' | 'b', 'a'>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'reports `Extract`',
+          code: 'type A = Extract<string | number, number>;',
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type StrictExtract } from 'ts-type-forge';
+                    type A = StrictExtract<string | number, number>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type RelaxedExtract } from 'ts-type-forge';
+                    type A = RelaxedExtract<string | number, number>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'reports `Omit`',
+          code: "type A = Omit<{ a: 1; b: 2 }, 'a'>;",
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type StrictOmit } from 'ts-type-forge';
+                    type A = StrictOmit<{ a: 1; b: 2 }, 'a'>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type RelaxedOmit } from 'ts-type-forge';
+                    type A = RelaxedOmit<{ a: 1; b: 2 }, 'a'>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'reports `Pick`',
+          code: "type A = Pick<{ a: 1; b: 2 }, 'a'>;",
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type StrictPick } from 'ts-type-forge';
+                    type A = StrictPick<{ a: 1; b: 2 }, 'a'>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type RelaxedPick } from 'ts-type-forge';
+                    type A = RelaxedPick<{ a: 1; b: 2 }, 'a'>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'touches no import under the `global` import style',
+          options: [{ importStyle: 'global' }],
+          code: "type A = Pick<{ a: 1 }, 'a'>;",
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: "type A = StrictPick<{ a: 1 }, 'a'>;",
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: "type A = RelaxedPick<{ a: 1 }, 'a'>;",
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'reuses an existing ts-type-forge import, alias included',
+          code: dedent`
+            import { type StrictPick as SPick } from 'ts-type-forge';
+            type A = Pick<{ a: 1 }, 'a'>;
+          `,
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Pick', replacement: 'SPick' },
+                  output: dedent`
+                    import { type StrictPick as SPick } from 'ts-type-forge';
+                    type A = SPick<{ a: 1 }, 'a'>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Pick', replacement: 'RelaxedPick' },
+                  output: dedent`
+                    import { type RelaxedPick } from 'ts-type-forge';
+                    import { type StrictPick as SPick } from 'ts-type-forge';
+                    type A = RelaxedPick<{ a: 1 }, 'a'>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'drops the suggestion whose target name is bound locally',
+          code: dedent`
+            type StrictOmit<T, K extends keyof T> = { readonly [P in K]: T[P] };
+            type A = Omit<{ a: 1; b: 2 }, 'a'>;
+          `,
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  data: { name: 'Omit', replacement: 'RelaxedOmit' },
+                  output: dedent`
+                    import { type RelaxedOmit } from 'ts-type-forge';
+                    type StrictOmit<T, K extends keyof T> = { readonly [P in K]: T[P] };
+                    type A = RelaxedOmit<{ a: 1; b: 2 }, 'a'>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'reports every occurrence, nesting included',
+          code: "type A = Pick<{ a: 1; b: 2 }, Exclude<'a' | 'b', 'b'>>;",
+          errors: [
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type StrictPick } from 'ts-type-forge';
+                    type A = StrictPick<{ a: 1; b: 2 }, Exclude<'a' | 'b', 'b'>>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type RelaxedPick } from 'ts-type-forge';
+                    type A = RelaxedPick<{ a: 1; b: 2 }, Exclude<'a' | 'b', 'b'>>;
+                  `,
+                },
+              ],
+            },
+            {
+              messageId: 'useStrictOrRelaxed',
+              suggestions: [
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type StrictExclude } from 'ts-type-forge';
+                    type A = Pick<{ a: 1; b: 2 }, StrictExclude<'a' | 'b', 'b'>>;
+                  `,
+                },
+                {
+                  messageId: 'replaceWith',
+                  output: dedent`
+                    import { type RelaxedExclude } from 'ts-type-forge';
+                    type A = Pick<{ a: 1; b: 2 }, RelaxedExclude<'a' | 'b', 'b'>>;
+                  `,
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  );
+});

package/src/rules/rules.mts

@@ -1,7 +1,11 @@
 import { type ESLintPlugin } from '../types.mjs';
 import { preferCanonicalLengthConstrainedTuple } from './prefer-canonical-length-constrained-tuple.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-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

@@ -0,0 +1,103 @@
+import {
+  AST_NODE_TYPES,
+  ASTUtils,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { Arr } from 'ts-data-forge';
+import { resolveTypeName, type ImportStyle } from './import-style.mjs';
+import { buildTypeImportFix } from './import-utils.mjs';
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+/**
+ * The ts-type-forge replacements offered for one standard-library type, in the
+ * order they are suggested.
+ */
+export type StdTypeAlternatives = ReadonlyMap<string, readonly string[]>;
+
+/**
+ * Reports a reference to a banned standard-library type and offers one
+ * suggestion per ts-type-forge alternative.
+ *
+ * Choosing between the alternatives is a semantic decision — `StrictExclude`
+ * additionally checks that the subtrahend is part of the union, `ReadonlyRecord`
+ * and `MutableRecord` describe different types — so this is deliberately *not*
+ * an autofix. Each suggestion carries its own import fix, which is safe because
+ * ESLint applies suggestions one at a time.
+ */
+export const reportStdTypeReference = <MessageIds extends string>(
+  context: TSESLint.RuleContext<MessageIds, readonly unknown[]>,
+  node: TSESTree.TSTypeReference,
+  alternatives: StdTypeAlternatives,
+  messageIds: Readonly<{ report: MessageIds; suggestion: MessageIds }>,
+  importStyle: ImportStyle,
+): void => {
+  const typeName = node.typeName;
+
+  // `ns.Pick` / `import('…').Pick` never denote the standard-library type.
+  if (typeName.type !== AST_NODE_TYPES.Identifier) return;
+
+  const stdName = typeName.name;
+
+  const candidates = alternatives.get(stdName);
+
+  if (candidates === undefined) return;
+
+  // A file that declares — or imports — its own `Pick` does not mean the
+  // standard-library one, so there is nothing to steer.
+  if (isLocallyBound(context.sourceCode, node, stdName)) return;
+
+  const program = context.sourceCode.ast;
+
+  context.report({
+    node: typeName,
+    messageId: messageIds.report,
+    data: { name: stdName, alternatives: formatAlternatives(candidates) },
+    suggest: candidates.flatMap((candidate) => {
+      const target = resolveTypeName(program, candidate, importStyle);
+
+      // The replacement name is already bound to something else in this file,
+      // so rewriting to it would resolve to the wrong declaration.
+      return target === undefined
+        ? []
+        : [
+            {
+              messageId: messageIds.suggestion,
+              data: { name: stdName, replacement: target.localName },
+              fix: (fixer: TSESLint.RuleFixer): readonly TSESLint.RuleFix[] =>
+                Arr.toPushed(
+                  target.needsImport
+                    ? buildTypeImportFix(fixer, program, candidate)
+                    : [],
+                  fixer.replaceText(typeName, target.localName),
+                ),
+            },
+          ];
+    }),
+  });
+};
+
+/** `['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/src/rules/tuple-rule-utils.mts

@@ -1,66 +1,10 @@
 import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
 import { Arr } from 'ts-data-forge';
-import { TS_TYPE_FORGE_MODULE } from './constants.mjs';
-import {
-  buildTypeImportFix,
-  getImportedLocalName,
-  getTsTypeForgeImports,
-  hasConflictingDeclaration,
-} from './import-utils.mjs';
+import { resolveTypeName, type ImportStyle } from './import-style.mjs';
+import { buildTypeImportFix } from './import-utils.mjs';
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
 
-/** `JSONSchema4`, reached through the public rule-module types. */
-type JsonSchema = Exclude<
-  TSESLint.RuleModule<string, readonly unknown[]>['meta']['schema'],
-  readonly unknown[]
->;
-
-export type ImportStyle = 'global' | 'named';
-
-export const DEFAULT_IMPORT_STYLE: ImportStyle = 'named';
-
-export const IMPORT_STYLE_SCHEMA_PROPERTY: JsonSchema = {
-  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_MODULE}';\``,
-    "when the name is not imported yet; 'global' assumes the",
-    'ambient globals of `ts-type-forge/global` and never touches',
-    'imports.',
-  ].join(' '),
-};
-
-/**
- * Resolves how a ts-type-forge type name should be written in this file, and
- * whether the autofix has to add an import for it.
- *
- * Returns `undefined` when the name is already bound to something else (a local
- * alias, or an import from another module) — rewriting to it would then silently
- * resolve to the wrong declaration, which is exactly what happens inside
- * ts-type-forge's own sources.
- */
-export const resolveTypeName = (
-  program: TSESTree.Program,
-  canonicalName: string,
-  importStyle: ImportStyle,
-): Readonly<{ localName: string; needsImport: boolean }> | undefined => {
-  const importedLocalName = getImportedLocalName(
-    getTsTypeForgeImports(program),
-    canonicalName,
-  );
-
-  if (importedLocalName !== undefined) {
-    return { localName: importedLocalName, needsImport: false };
-  }
-
-  return hasConflictingDeclaration(program, canonicalName)
-    ? undefined
-    : { localName: canonicalName, needsImport: importStyle === 'named' };
-};
-
 export type TupleRewrite = Readonly<{
   node: TSESTree.Node;
   canonicalName: string;