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

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,65 +1,10 @@
 import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
-import { TS_TYPE_FORGE_MODULE } from './constants.mjs';
-import {
-  buildTypeImportFix,
-  getImportedLocalName,
-  getTsTypeForgeImports,
-  hasConflictingDeclaration,
-} from './import-utils.mjs';
+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 */
 
-/** `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 = 'global';
-
-export const IMPORT_STYLE_SCHEMA_PROPERTY: JsonSchema = {
-  type: 'string',
-  enum: ['global', 'named'],
-  description: [
-    'How the ts-type-forge type is brought into scope.',
-    "'global' (default) assumes the ambient globals of",
-    '`ts-type-forge/global` and never touches imports;',
-    "'named' makes the autofix add the corresponding",
-    `\`import { type … } from '${TS_TYPE_FORGE_MODULE}';\``,
-    'when the name is not imported yet.',
-  ].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;
@@ -109,14 +54,15 @@ export const reportTupleRewrites = <MessageIds extends string>(
       node: rewrite.node,
       messageId,
       data: { original: sourceCode.getText(rewrite.node), replacement },
-      fix: (fixer) => [
-        ...(index === 0
-          ? importNames.flatMap((name) =>
-              buildTypeImportFix(fixer, program, name),
-            )
-          : []),
-        fixer.replaceText(rewrite.node, replacement),
-      ],
+      fix: (fixer) =>
+        Arr.toPushed(
+          index === 0
+            ? importNames.flatMap((name) =>
+                buildTypeImportFix(fixer, program, name),
+              )
+            : [],
+          fixer.replaceText(rewrite.node, replacement),
+        ),
     });
   }
 };