eslint-rule-forge 0.3.2 → 0.5.0

package/src/rules/prefer-safe-parse.mts

@@ -5,11 +5,8 @@ import {
 } from '@typescript-eslint/utils';
 import type { ReadonlyRecord } from 'ts-type-forge';
 import * as ts from 'typescript';
-import {
-  buildNamedImportFix,
-  getImportDeclarations,
-  getNamedImports,
-} from '../imports.mjs';
+import { hasForeignBinding } from '../bindings.mjs';
+import { bindValueImports } from '../imports.mjs';
 import { getArgumentText } from '../parentheses.mjs';
 import {
   isIdentifierNamed,
@@ -33,16 +30,20 @@ export type SafeParseRuleConfig = Readonly<{
 }>;
 
 /**
- * Builds a rule that replaces the base-10 forms of `parseInt` and
- * `Number.parseInt` — `parseInt(x)` and `parseInt(x, 10)` — with
- * `Result.unwrapOkOr(<namespace>.<method>(x), Number.NaN)`.
+ * Builds a rule that reports the base-10 forms of `parseInt` and
+ * `Number.parseInt` — `parseInt(x)` and `parseInt(x, 10)` — and suggests
+ * `Result.unwrapOkOr(<namespace>.<method>(x), Number.NaN)` instead. A
+ * suggestion, not an autofix: the replacement reads some strings differently.
  *
  * A call that passes another radix is left alone: the replacement takes none,
  * so it would mean something the replacement cannot say.
  */
 export const createPreferSafeParseInt = (
   config: SafeParseRuleConfig,
-): TSESLint.RuleModule<'useSafeParseInt', readonly []> =>
+): TSESLint.RuleModule<
+  'useSafeParseInt' | 'replaceWithSafeParse',
+  readonly []
+> =>
   createSafeParseRule(config, 'useSafeParseInt', {
     messages: { useSafeParseInt: messageText(config) },
     description: `Replace \`parseInt(x)\` or \`Number.parseInt(x, 10)\` with \`Result.unwrapOkOr(${config.namespace}.${config.method}(x), Number.NaN)\` from ${config.moduleName}.`,
@@ -54,8 +55,8 @@ export const createPreferSafeParseInt = (
         return false;
       }
 
-      // Only base 10: accept a missing radix or an explicit literal `10`,
-      // read through its type wrappers, which leave the value as it is.
+      // Only base 10: accept a missing radix or an explicit literal `10`, read
+      // through its type wrappers, which leave the value as it is.
       const radix =
         args[1] === undefined ? undefined : skipTypeWrappers(args[1]);
 
@@ -67,15 +68,20 @@ export const createPreferSafeParseInt = (
   });
 
 /**
- * Builds a rule that replaces `parseFloat(x)`, `Number.parseFloat(x)` and
- * `Number(x)` with `Result.unwrapOkOr(<namespace>.<method>(x), Number.NaN)`.
+ * Builds a rule that reports `parseFloat(x)`, `Number.parseFloat(x)` and
+ * `Number(x)`, and suggests
+ * `Result.unwrapOkOr(<namespace>.<method>(x), Number.NaN)` instead, as a
+ * suggestion for the same reason.
  *
  * Like every rewrite here, `Number(x)` is only flagged when `x` is purely a
  * `string`, which leaves `Number(someBoolean)` and `Number(someNumber)` alone.
  */
 export const createPreferSafeParseFloat = (
   config: SafeParseRuleConfig,
-): TSESLint.RuleModule<'useSafeParseFloat', readonly []> =>
+): TSESLint.RuleModule<
+  'useSafeParseFloat' | 'replaceWithSafeParse',
+  readonly []
+> =>
   createSafeParseRule(config, 'useSafeParseFloat', {
     messages: { useSafeParseFloat: messageText(config) },
     description: `Replace \`parseFloat(x)\`, \`Number.parseFloat(x)\`, or \`Number(x)\` (when x is a string) with \`Result.unwrapOkOr(${config.namespace}.${config.method}(x), Number.NaN)\` from ${config.moduleName}.`,
@@ -89,6 +95,20 @@ export const createPreferSafeParseFloat = (
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
 
+/**
+ * Whether every constituent of `type` is string-like, i.e. the type is
+ * assignable to the parse function's `string` parameter. A union such as
+ * `string | undefined` is rejected so the suggestion never produces a type error.
+ */
+const isStringType = (type: ts.Type): boolean => {
+  const parts = type.isUnion() ? type.types : ([type] as const);
+
+  return (
+    parts.length > 0 &&
+    parts.every((t) => (t.flags & ts.TypeFlags.StringLike) !== 0)
+  );
+};
+
 const createSafeParseRule = <MessageId extends string>(
   { moduleName, namespace, method }: SafeParseRuleConfig,
   messageId: MessageId,
@@ -103,16 +123,14 @@ const createSafeParseRule = <MessageId extends string>(
 
     /**
      * Whether the call, its callee read through its type wrappers, is one to
-     * rewrite.
+     * report.
      */
     isTarget: (
       callee: TSESTree.Expression,
       args: readonly TSESTree.CallExpressionArgument[],
     ) => boolean;
   }>,
-): TSESLint.RuleModule<MessageId, readonly []> => {
-  const parseFunction = `${namespace}.${method}` as const;
-
+): TSESLint.RuleModule<MessageId | 'replaceWithSafeParse', readonly []> => {
   // Sorted, as an import sorter would write them.
   const requiredImports = [namespace, 'Result'].toSorted();
 
@@ -120,20 +138,19 @@ const createSafeParseRule = <MessageId extends string>(
     meta: {
       type: 'suggestion',
       docs: { description },
-      fixable: 'code',
+      hasSuggestions: true,
       schema: [],
-      messages,
+      messages: {
+        ...messages,
+        replaceWithSafeParse: `Replace with \`Result.unwrapOkOr(${namespace}.${method}({{argName}}), Number.NaN)\`.`,
+      },
       defaultOptions: [],
     },
 
     create: (context) => {
       const sourceCode = context.sourceCode;
 
-      const program = sourceCode.ast;
-
-      const moduleImports = getImportDeclarations(program, moduleName);
-
-      const mut_nodesToFix: {
+      const mut_reports: {
         node: TSESTree.CallExpression;
         argExpression: TSESTree.Expression;
       }[] = [];
@@ -146,8 +163,7 @@ const createSafeParseRule = <MessageId extends string>(
 
           const firstArg = node.arguments[0];
 
-          // A spread argument (`parseInt(...rest)`) cannot be rewritten
-          // safely.
+          // A spread argument (`parseInt(...rest)`) cannot be rewritten safely.
           if (
             firstArg === undefined ||
             firstArg.type === AST_NODE_TYPES.SpreadElement
@@ -157,56 +173,69 @@ const createSafeParseRule = <MessageId extends string>(
 
           // The argument must be purely `string` at every layer of type
           // wrappers: the value's own type is what the original sees at run
-          // time (`parseInt(1e21 as unknown as string)` is 1, the rewrite
-          // 1e21; `Number(true as unknown as string)` is 1, the rewrite NaN),
-          // and the type a wrapper states is what the fix, which keeps the
+          // time (`parseInt(1e21 as unknown as string)` is 1, the rewrite 1e21;
+          // `Number(true as unknown as string)` is 1, the rewrite NaN), and the
+          // type a wrapper states is what the suggestion, which keeps the
           // wrapper, hands the parse function's `string` parameter. Without
           // type information, skip.
           if (!typeHoldsAtEveryLayer(sourceCode, firstArg, isStringType)) {
             return;
           }
 
-          mut_nodesToFix.push({ node, argExpression: firstArg });
+          mut_reports.push({ node, argExpression: firstArg });
         },
         'Program:exit': () => {
-          const namedImports = getNamedImports(moduleImports);
-
-          const missingImports = requiredImports.filter(
-            (name) => !namedImports.includes(name),
+          const binding = bindValueImports(
+            sourceCode,
+            moduleName,
+            requiredImports,
           );
 
-          // The import fix lives on the first report only:
-          // `insertTextBefore(program, …)` produces overlapping ranges
-          // otherwise and only one of them would survive a pass.
-          for (const [
-            index,
-            { node, argExpression },
-          ] of mut_nodesToFix.entries()) {
+          const localNameOf = (name: string): string | undefined =>
+            binding?.localNames[requiredImports.indexOf(name)];
+
+          const namespaceName = localNameOf(namespace);
+
+          const resultName = localNameOf('Result');
+
+          // A suggestion, never an autofix: the replacement parses some
+          // strings differently (`parseInt('1e3')` is 1, the rewrite 1000;
+          // `parseFloat('12px')` is 12, the rewrite NaN; `Number('')` is 0, the
+          // rewrite NaN), so applying it is a person's decision. Each one
+          // brings its names into scope itself, so that it is complete alone.
+          for (const { node, argExpression } of mut_reports) {
             const argText = getArgumentText(sourceCode, argExpression);
 
+            const data = {
+              original: sourceCode.getText(node),
+              argName: argText,
+            } as const;
+
             context.report({
               node,
               messageId,
-              data: {
-                original: sourceCode.getText(node),
-                argName: argText,
-              },
-              fix: (fixer) => {
-                const core =
-                  `Result.unwrapOkOr(${parseFunction}(${argText}), Number.NaN)` as const;
-
-                const importFixes =
-                  index === 0 && missingImports.length > 0
-                    ? buildNamedImportFix(
-                        fixer,
-                        program,
-                        moduleName,
-                        missingImports,
-                      )
-                    : ([] as const);
-
-                return [...importFixes, fixer.replaceText(node, core)];
-              },
+              data,
+              suggest:
+                binding === undefined ||
+                namespaceName === undefined ||
+                resultName === undefined ||
+                [namespaceName, resultName].some((name) =>
+                  hasForeignBinding(sourceCode, node, name, moduleName),
+                )
+                  ? []
+                  : [
+                      {
+                        messageId: 'replaceWithSafeParse',
+                        data,
+                        fix: (fixer) => [
+                          ...binding.edits(fixer),
+                          fixer.replaceText(
+                            node,
+                            `${resultName}.unwrapOkOr(${namespaceName}.${method}(${argText}), Number.NaN)`,
+                          ),
+                        ],
+                      },
+                    ],
             });
           }
         },
@@ -220,7 +249,7 @@ const messageText = ({
   namespace,
   method,
 }: SafeParseRuleConfig): string =>
-  `Replace \`{{original}}\` with \`Result.unwrapOkOr(${namespace}.${method}({{argName}}), Number.NaN)\` from ${moduleName}.` as const;
+  `Replace \`{{original}}\` with \`Result.unwrapOkOr(${namespace}.${method}({{argName}}), Number.NaN)\` from ${moduleName}. It parses some strings differently from the call it replaces, so check the input before applying it.` as const;
 
 /** Whether `callee` is the global function `name`, as in `parseInt(...)`. */
 const isGlobalCall = (callee: TSESTree.Expression, name: string): boolean =>
@@ -236,17 +265,3 @@ const isNumberMethod = (callee: TSESTree.Expression, name: string): boolean =>
   isIdentifierNamed(callee.object, 'Number') &&
   callee.property.type === AST_NODE_TYPES.Identifier &&
   callee.property.name === name;
-
-/**
- * Whether every constituent of `type` is string-like, i.e. the type is
- * assignable to the parse function's `string` parameter. A union such as
- * `string | undefined` is rejected so the autofix never produces a type error.
- */
-const isStringType = (type: ts.Type): boolean => {
-  const parts = type.isUnion() ? type.types : ([type] as const);
-
-  return (
-    parts.length > 0 &&
-    parts.every((t) => (t.flags & ts.TypeFlags.StringLike) !== 0)
-  );
-};

package/src/statements.mts

@@ -0,0 +1,57 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+import type { DeepReadonly } from 'ts-type-forge';
+
+/**
+ * The statement next to `node` (`offset` 1) or before it (-1) in the statement
+ * list `node` is one of: the program's, a block's, a class static block's, a
+ * namespace's or a `case`'s. What an `export` declares (or, for
+ * `export default`, the expression it exports) is read as the `export`
+ * statement. `undefined` when there is none, or when `node` is not in a
+ * statement list (an arrow function's expression body, a `for` initializer).
+ */
+export const siblingOf = (
+  node: DeepReadonly<TSESTree.Node>,
+  offset: 1 | -1,
+): DeepReadonly<TSESTree.Node> | undefined => {
+  const { parent } = node;
+
+  const statement =
+    (parent?.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+      parent?.type === AST_NODE_TYPES.ExportDefaultDeclaration) &&
+    parent.declaration === node
+      ? parent
+      : node;
+
+  const list = statementListOf(statement);
+
+  if (list === undefined) {
+    return undefined;
+  }
+
+  const index = list.indexOf(statement);
+
+  return index === -1 ? undefined : list[index + offset];
+};
+
+const statementListOf = (
+  node: DeepReadonly<TSESTree.Node>,
+): readonly DeepReadonly<TSESTree.Node>[] | undefined => {
+  const { parent } = node;
+
+  if (parent === undefined) {
+    return undefined;
+  }
+
+  if (
+    parent.type === AST_NODE_TYPES.Program ||
+    parent.type === AST_NODE_TYPES.BlockStatement ||
+    parent.type === AST_NODE_TYPES.StaticBlock ||
+    parent.type === AST_NODE_TYPES.TSModuleBlock
+  ) {
+    return parent.body;
+  }
+
+  return parent.type === AST_NODE_TYPES.SwitchCase
+    ? parent.consequent
+    : undefined;
+};

package/src/type-wrappers.mts

@@ -89,9 +89,9 @@ export const isIdentifierNamed = (
  * Whether `holds` is true of the type of every layer of type wrappers around
  * `node` (see {@link typeWrapperLayers}), outermost to innermost; `false`
  * without type information. A widening cast (`s as string | number`) is the
- * author saying the value may be more than it is, and is respected; a
- * narrowing one (`s!`, `v as unknown as string`) cannot vouch for what the
- * value's own type does not, and the fix, which keeps the wrapper, has to
+ * author saying the value may be more than it is, and is respected; a narrowing
+ * one (`s!`, `v as unknown as string`) cannot vouch for what the value's own
+ * type does not, and the fix, which keeps the wrapper, has to
  * type-check at every layer too.
  */
 export const typeHoldsAtEveryLayer = (