eslint-rule-forge 0.2.0 → 0.3.1

package/src/rules/prefer-is-record-and-has-key.mts

@@ -0,0 +1,321 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import * as ts from 'typescript';
+import {
+  buildNamedImportFix,
+  getImportDeclarations,
+  getNamedImports,
+} from '../imports.mjs';
+import { getArgumentText } from '../parentheses.mjs';
+import {
+  isIdentifierNamed,
+  skipTypeWrappers,
+  typeHoldsAtEveryLayer,
+} from '../type-wrappers.mjs';
+
+/**
+ * Builds a rule that replaces `Object.hasOwn(obj, key)` and `key in obj` with
+ * `isRecord(obj) && hasKey(obj, key)` imported from `moduleName`, or with
+ * `hasKey(obj, key)` alone when `obj` is already a record.
+ */
+export const createPreferIsRecordAndHasKey = ({
+  moduleName,
+}: Readonly<{
+  /** The module that exports `isRecord` and `hasKey`. */
+  moduleName: string;
+}>): TSESLint.RuleModule<'useIsRecordAndHasKey' | 'useHasKey', readonly []> =>
+  ({
+    meta: {
+      type: 'suggestion',
+      docs: {
+        description: `Replace \`Object.hasOwn(obj, key)\` or \`key in obj\` with \`isRecord(obj) && hasKey(obj, key)\` from ${moduleName}`,
+      },
+      fixable: 'code',
+      schema: [],
+      messages: {
+        useIsRecordAndHasKey: `Replace \`{{original}}\` with \`isRecord({{objName}}) && hasKey({{objName}}, {{keyName}})\` from ${moduleName}.`,
+        useHasKey: `Replace \`{{original}}\` with \`hasKey({{objName}}, {{keyName}})\` from ${moduleName}.`,
+      },
+    },
+
+    create: (context) => {
+      const sourceCode = context.sourceCode;
+
+      const program = sourceCode.ast;
+
+      const moduleImports = getImportDeclarations(program, moduleName);
+
+      /**
+       * Whether the `isRecord(...)` half of the rewrite would be dead code
+       * because the object already satisfies `hasKey`'s
+       * `R extends UnknownRecord` constraint, at every layer of type
+       * wrappers: an array cast to a record is still rejected by `isRecord`,
+       * and a record widened to one that may be an array is the author saying
+       * it may need the guard. Without type information nothing is known, so
+       * the guard is kept.
+       */
+      const isKnownRecord = (
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        expression: TSESTree.Expression,
+      ): boolean =>
+        typeHoldsAtEveryLayer(sourceCode, expression, (type, checker) =>
+          isAlreadyRecordType(checker, type),
+        );
+
+      /**
+       * Whether the object may be an array at some layer of type wrappers.
+       * `isRecord` rejects an array, so `'0' in xs` would turn from `true` to
+       * `false`; a widening cast to a type that may be an array is the author
+       * saying it may be one. Without type information nothing is known, and
+       * the rule reports as it always has.
+       */
+      const mayBeArray = (
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        expression: TSESTree.Expression,
+      ): boolean =>
+        sourceCode.parserServices?.program != null &&
+        !typeHoldsAtEveryLayer(
+          sourceCode,
+          expression,
+          (type, checker) => !mayBeArrayType(checker, type),
+        );
+
+      const mut_nodesToFix: {
+        node: TSESTree.CallExpression | TSESTree.BinaryExpression;
+        objExpression: TSESTree.Expression;
+        keyExpression: TSESTree.Expression;
+      }[] = [];
+
+      return {
+        // Handle Object.hasOwn(obj, key)
+        CallExpression: (node) => {
+          const callee = skipTypeWrappers(node.callee);
+
+          if (
+            callee.type !== AST_NODE_TYPES.MemberExpression ||
+            !isIdentifierNamed(callee.object, 'Object') ||
+            callee.property.type !== AST_NODE_TYPES.Identifier ||
+            callee.property.name !== 'hasOwn'
+          ) {
+            return;
+          }
+
+          // Check arguments: Object.hasOwn(obj, key)
+          if (node.arguments.length !== 2) {
+            return;
+          }
+
+          const objArg = node.arguments[0];
+
+          const keyArg = node.arguments[1];
+
+          if (objArg === undefined || keyArg === undefined) {
+            return;
+          }
+
+          // Type guard: ensure arguments are Expressions (not SpreadElement)
+          if (
+            objArg.type === AST_NODE_TYPES.SpreadElement ||
+            keyArg.type === AST_NODE_TYPES.SpreadElement ||
+            mayBeArray(objArg)
+          ) {
+            return;
+          }
+
+          mut_nodesToFix.push({
+            node,
+            objExpression: objArg,
+            keyExpression: keyArg,
+          });
+        },
+
+        // Handle key in obj
+        BinaryExpression: (node) => {
+          if (node.operator !== 'in') {
+            return;
+          }
+
+          const keyExpression = node.left;
+
+          const objExpression = node.right;
+
+          // Type guard: ensure keyExpression is Expression (not PrivateIdentifier)
+          if (
+            keyExpression.type === AST_NODE_TYPES.PrivateIdentifier ||
+            mayBeArray(objExpression)
+          ) {
+            return;
+          }
+
+          mut_nodesToFix.push({
+            node,
+            objExpression,
+            keyExpression,
+          });
+        },
+
+        'Program:exit': () => {
+          const namedImports = getNamedImports(moduleImports);
+
+          const rewrites = mut_nodesToFix.map((entry) => {
+            // A record-typed object makes the `isRecord(...)` conjunct always
+            // true, so it is left out of the replacement entirely.
+            const needsIsRecord = !isKnownRecord(entry.objExpression);
+
+            return {
+              ...entry,
+              needsIsRecord,
+              // `isRecord(obj) && hasKey(obj, key)` evaluates `obj` twice.
+              fixable: !needsIsRecord || isSideEffectFree(entry.objExpression),
+            };
+          });
+
+          const fixableRewrites = rewrites.filter(({ fixable }) => fixable);
+
+          const importsToAdd: readonly string[] =
+            fixableRewrites.length === 0
+              ? []
+              : [
+                  ...(fixableRewrites.some(
+                    ({ needsIsRecord }) => needsIsRecord,
+                  ) && !namedImports.includes('isRecord')
+                    ? ['isRecord']
+                    : []),
+                  ...(namedImports.includes('hasKey') ? [] : ['hasKey']),
+                ];
+
+          const importCarrier = fixableRewrites[0];
+
+          for (const rewrite of rewrites) {
+            const { node, objExpression, keyExpression, needsIsRecord } =
+              rewrite;
+
+            const objText = getArgumentText(sourceCode, objExpression);
+
+            const keyText = getArgumentText(sourceCode, keyExpression);
+
+            const originalText = sourceCode.getText(node);
+
+            context.report({
+              node,
+              messageId: needsIsRecord ? 'useIsRecordAndHasKey' : 'useHasKey',
+              data: {
+                original: originalText,
+                objName: objText,
+                keyName: keyText,
+              },
+              fix: !rewrite.fixable
+                ? undefined
+                : (fixer) => {
+                    const replacement = needsIsRecord
+                      ? `(isRecord(${objText}) && hasKey(${objText}, ${keyText}))`
+                      : `hasKey(${objText}, ${keyText})`;
+
+                    // All import fixes have to live on the first fixable
+                    // report: `insertTextBefore(program, …)` produces
+                    // overlapping ranges otherwise and only one of them would
+                    // survive a pass.
+                    const importFixes =
+                      rewrite === importCarrier && importsToAdd.length > 0
+                        ? buildNamedImportFix(
+                            fixer,
+                            program,
+                            moduleName,
+                            importsToAdd,
+                          )
+                        : [];
+
+                    return [
+                      ...importFixes,
+                      fixer.replaceText(node, replacement),
+                    ];
+                  },
+            });
+          }
+        },
+      };
+    },
+    defaultOptions: [],
+  }) as const;
+
+/**
+ * Whether reading `node` again has no side effects: a variable, `this`, or a
+ * non-computed property chain on one, type wrappers aside.
+ */
+const isSideEffectFree = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  wrapped: TSESTree.Node,
+): boolean => {
+  const node = skipTypeWrappers(wrapped);
+
+  return (
+    node.type === AST_NODE_TYPES.Identifier ||
+    node.type === AST_NODE_TYPES.ThisExpression ||
+    (node.type === AST_NODE_TYPES.MemberExpression &&
+      !node.computed &&
+      isSideEffectFree(node.object))
+  );
+};
+
+/**
+ * Whether a value of `type` may be an array or a tuple: some member of a union
+ * or an intersection is one, or the constraint of a deferred type is.
+ * `object` and `unknown` say nothing either way and are not counted.
+ */
+const mayBeArrayType = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  checker: ts.TypeChecker,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  type: ts.Type,
+): boolean => {
+  if (type.isUnionOrIntersection()) {
+    return type.types.some((member) => mayBeArrayType(checker, member));
+  }
+
+  if (
+    (type.flags &
+      (ts.TypeFlags.TypeParameter |
+        ts.TypeFlags.IndexedAccess |
+        ts.TypeFlags.Conditional |
+        ts.TypeFlags.Substitution)) !==
+    0
+  ) {
+    const constraint = checker.getBaseConstraintOfType(type);
+
+    return constraint !== undefined && mayBeArrayType(checker, constraint);
+  }
+
+  return checker.isArrayType(type) || checker.isTupleType(type);
+};
+
+/**
+ * Whether `type` already satisfies `hasKey`'s `R extends UnknownRecord`
+ * constraint, so that guarding the call with `isRecord` adds nothing.
+ *
+ * `UnknownRecord` is `ReadonlyRecord<string, unknown>`, so a string index
+ * signature is exactly what it asks for and its value type is `unknown`, which
+ * anything satisfies. Callables and arrays are excluded because `isRecord`
+ * rejects them at runtime (`typeof fn === 'object'` is false, `Array.isArray`
+ * is true), so dropping the guard there would change behavior.
+ *
+ * Deliberately conservative: a type TypeScript would accept through an
+ * *implicit* index signature (an object type alias without one of its own)
+ * keeps the guard, because the checker does not report such a signature here.
+ */
+const isAlreadyRecordType = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  checker: ts.TypeChecker,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  type: ts.Type,
+): boolean =>
+  type.isUnion()
+    ? type.types.every((member) => isAlreadyRecordType(checker, member))
+    : checker.getIndexInfoOfType(type, ts.IndexKind.String) !== undefined &&
+      checker.getSignaturesOfType(type, ts.SignatureKind.Call).length === 0 &&
+      checker.getSignaturesOfType(type, ts.SignatureKind.Construct).length ===
+        0 &&
+      !checker.isArrayType(type) &&
+      !checker.isTupleType(type);

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

@@ -0,0 +1,252 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import type { ReadonlyRecord } from 'ts-type-forge';
+import * as ts from 'typescript';
+import {
+  buildNamedImportFix,
+  getImportDeclarations,
+  getNamedImports,
+} from '../imports.mjs';
+import { getArgumentText } from '../parentheses.mjs';
+import {
+  isIdentifierNamed,
+  skipTypeWrappers,
+  typeHoldsAtEveryLayer,
+} from '../type-wrappers.mjs';
+
+/** What {@link createPreferSafeParseInt} and its float twin are told. */
+export type SafeParseRuleConfig = Readonly<{
+  /** The module that exports `namespace` and `Result`. */
+  moduleName: string;
+
+  /** The exported namespace the parse function is reached through. */
+  namespace: string;
+
+  /**
+   * The member of `namespace` that parses a `string` into a
+   * `Result<number, …>`.
+   */
+  method: string;
+}>;
+
+/**
+ * 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)`.
+ *
+ * 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 []> =>
+  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}.`,
+    isTarget: (callee, args) => {
+      if (
+        !isGlobalCall(callee, 'parseInt') &&
+        !isNumberMethod(callee, 'parseInt')
+      ) {
+        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.
+      const radix =
+        args[1] === undefined ? undefined : skipTypeWrappers(args[1]);
+
+      return (
+        radix === undefined ||
+        (radix.type === AST_NODE_TYPES.Literal && radix.value === 10)
+      );
+    },
+  });
+
+/**
+ * Builds a rule that replaces `parseFloat(x)`, `Number.parseFloat(x)` and
+ * `Number(x)` with `Result.unwrapOkOr(<namespace>.<method>(x), Number.NaN)`.
+ *
+ * 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 []> =>
+  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}.`,
+    // `Number(...)` is matched only as a call; `new Number(...)` is a
+    // `NewExpression`, which this rule never visits.
+    isTarget: (callee) =>
+      isGlobalCall(callee, 'parseFloat') ||
+      isNumberMethod(callee, 'parseFloat') ||
+      isGlobalCall(callee, 'Number'),
+  });
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+const createSafeParseRule = <MessageId extends string>(
+  { moduleName, namespace, method }: SafeParseRuleConfig,
+  messageId: MessageId,
+  {
+    messages,
+    description,
+    isTarget,
+  }: Readonly<{
+    messages: ReadonlyRecord<MessageId, string>;
+
+    description: string;
+
+    /**
+     * Whether the call, its callee read through its type wrappers, is one to
+     * rewrite.
+     */
+    isTarget: (
+      callee: TSESTree.Expression,
+      args: readonly TSESTree.CallExpressionArgument[],
+    ) => boolean;
+  }>,
+): TSESLint.RuleModule<MessageId, readonly []> => {
+  const parseFunction = `${namespace}.${method}` as const;
+
+  // Sorted, as an import sorter would write them.
+  const requiredImports = [namespace, 'Result'].toSorted();
+
+  return {
+    meta: {
+      type: 'suggestion',
+      docs: { description },
+      fixable: 'code',
+      schema: [],
+      messages,
+    },
+
+    create: (context) => {
+      const sourceCode = context.sourceCode;
+
+      const program = sourceCode.ast;
+
+      const moduleImports = getImportDeclarations(program, moduleName);
+
+      const mut_nodesToFix: {
+        node: TSESTree.CallExpression;
+        argExpression: TSESTree.Expression;
+      }[] = [];
+
+      return {
+        CallExpression: (node) => {
+          if (!isTarget(skipTypeWrappers(node.callee), node.arguments)) {
+            return;
+          }
+
+          const firstArg = node.arguments[0];
+
+          // A spread argument (`parseInt(...rest)`) cannot be rewritten
+          // safely.
+          if (
+            firstArg === undefined ||
+            firstArg.type === AST_NODE_TYPES.SpreadElement
+          ) {
+            return;
+          }
+
+          // 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
+          // wrapper, hands the parse function's `string` parameter. Without
+          // type information, skip.
+          if (!typeHoldsAtEveryLayer(sourceCode, firstArg, isStringType)) {
+            return;
+          }
+
+          mut_nodesToFix.push({ node, argExpression: firstArg });
+        },
+        'Program:exit': () => {
+          const namedImports = getNamedImports(moduleImports);
+
+          const missingImports = requiredImports.filter(
+            (name) => !namedImports.includes(name),
+          );
+
+          // 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 argText = getArgumentText(sourceCode, argExpression);
+
+            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)];
+              },
+            });
+          }
+        },
+      };
+    },
+    defaultOptions: [],
+  } as const;
+};
+
+const messageText = ({
+  moduleName,
+  namespace,
+  method,
+}: SafeParseRuleConfig): string =>
+  `Replace \`{{original}}\` with \`Result.unwrapOkOr(${namespace}.${method}({{argName}}), Number.NaN)\` from ${moduleName}.` as const;
+
+/** Whether `callee` is the global function `name`, as in `parseInt(...)`. */
+const isGlobalCall = (callee: TSESTree.Expression, name: string): boolean =>
+  callee.type === AST_NODE_TYPES.Identifier && callee.name === name;
+
+/**
+ * Whether `callee` is `Number.<name>`, the `Number` read through its type
+ * wrappers.
+ */
+const isNumberMethod = (callee: TSESTree.Expression, name: string): boolean =>
+  callee.type === AST_NODE_TYPES.MemberExpression &&
+  !callee.computed &&
+  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/type-wrappers.mts

@@ -1,5 +1,10 @@
-import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
 import type { DeepReadonly, RelaxedExtract } from 'ts-type-forge';
+import type * as ts from 'typescript';
 
 /**
  * The four expressions that change a value's type and nothing else: `x as T`,
@@ -65,6 +70,55 @@ export const typeWrapperLayers = <N extends DeepReadonly<TSESTree.Node>>(
     ? ([node, ...typeWrapperLayers(node.expression)] as const)
     : ([node] as const);
 
+/**
+ * Whether `node`, read through its type wrappers, is the identifier `name`:
+ * `Number`, `(Number as NumberConstructor)` and `Number!` are the same object.
+ */
+export const isIdentifierNamed = (
+  node: DeepReadonly<TSESTree.Node>,
+  name: string,
+): boolean => {
+  const unwrapped = skipTypeWrappers(node);
+
+  return (
+    unwrapped.type === AST_NODE_TYPES.Identifier && unwrapped.name === name
+  );
+};
+
+/**
+ * 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
+ * type-check at every layer too.
+ */
+export const typeHoldsAtEveryLayer = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Node,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  holds: (type: ts.Type, typeChecker: ts.TypeChecker) => boolean,
+): boolean => {
+  const services = sourceCode.parserServices;
+
+  const checker = services?.program?.getTypeChecker();
+
+  if (checker === undefined) {
+    return false;
+  }
+
+  return typeWrapperLayers(node).every((layer) => {
+    const tsNode = services?.esTreeNodeToTSNodeMap?.get(layer);
+
+    return (
+      tsNode !== undefined && holds(checker.getTypeAtLocation(tsNode), checker)
+    );
+  });
+};
+
 const TYPE_WRAPPERS: ReadonlySet<AST_NODE_TYPES> = new Set([
   AST_NODE_TYPES.TSAsExpression,
   AST_NODE_TYPES.TSNonNullExpression,