eslint-plugin-ts-std-forge 0.1.0

package/src/rules/prefer-safe-array-length-guard.mts

@@ -0,0 +1,214 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { type ReadonlyRecord } from 'ts-type-forge';
+import {
+  buildImportFixes,
+  getNamedImports,
+  getTsStdForgeImport,
+} from './import-utils.mjs';
+
+type Options = readonly [];
+
+type MessageIds = 'useIsEmpty' | 'useIsNonEmpty';
+
+type Guard = 'isEmpty' | 'isNonEmpty';
+
+/**
+ * The length comparisons that say "empty" or "non-empty" and nothing more,
+ * written with `.length` on the left. A comparison with the operands the other
+ * way round is normalized by flipping the operator before this is consulted.
+ *
+ * Only these two questions are here because only these two guards exist:
+ * ts-data-forge answers `xs.length >= n` for an arbitrary `n` with
+ * `Arr.isMinLengthArray` and the rest of the branded length family, which
+ * ts-std-forge deliberately has no counterpart for (D-26 / D-39).
+ */
+const COMPARISONS = [
+  { operator: '===', bound: 0, guard: 'isEmpty' },
+  { operator: '!==', bound: 0, guard: 'isNonEmpty' },
+  { operator: '>', bound: 0, guard: 'isNonEmpty' },
+  { operator: '>=', bound: 1, guard: 'isNonEmpty' },
+] as const satisfies readonly Readonly<{
+  operator: string;
+  bound: number;
+  guard: Guard;
+}>[];
+
+/** The operator that means the same thing with the operands swapped. */
+const FLIPPED: ReadonlyRecord<string, string> = {
+  '===': '===',
+  '!==': '!==',
+  '>': '<',
+  '<': '>',
+  '>=': '<=',
+  '<=': '>=',
+} as const;
+
+const MESSAGE_IDS: ReadonlyRecord<Guard, MessageIds> = {
+  isEmpty: 'useIsEmpty',
+  isNonEmpty: 'useIsNonEmpty',
+} as const;
+
+export const preferSafeArrayLengthGuard: TSESLint.RuleModule<
+  MessageIds,
+  Options
+> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Replace an emptiness check on an array (`xs.length === 0`, `xs.length > 0`, `xs.length >= 1`, `xs.length !== 0`) with `SafeArray.isEmpty(xs)` / `SafeArray.isNonEmpty(xs)` from ts-std-forge.',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      useIsEmpty:
+        'Replace `{{original}}` with `SafeArray.isEmpty({{arrayName}})` from ts-std-forge: the comparison narrows nothing, the guard narrows to `readonly []`.',
+      useIsNonEmpty:
+        'Replace `{{original}}` with `SafeArray.isNonEmpty({{arrayName}})` from ts-std-forge: the comparison narrows nothing, so `{{arrayName}}[0]` stays `| undefined`.',
+    },
+  },
+
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+
+    const program = sourceCode.ast;
+
+    const tsStdForgeImport = getTsStdForgeImport(program);
+
+    const services = sourceCode.parserServices;
+
+    const checker = services?.program?.getTypeChecker();
+
+    /**
+     * Whether `expression` is an array or tuple. Without type information the
+     * answer is no: `.length` is also a string's, a function's and a
+     * `TypedArray`'s, and none of those can be handed to the guard.
+     */
+    const isArrayLike = (
+      // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+      expression: TSESTree.Expression,
+    ): boolean => {
+      if (checker === undefined) return false;
+
+      const tsNode = services?.esTreeNodeToTSNodeMap?.get(expression);
+
+      if (tsNode === undefined) return false;
+
+      const type = checker.getTypeAtLocation(tsNode);
+
+      return checker.isArrayType(type) || checker.isTupleType(type);
+    };
+
+    const mut_nodesToFix: {
+      node: TSESTree.BinaryExpression;
+      arrayExpression: TSESTree.Expression;
+      guard: Guard;
+    }[] = [];
+
+    return {
+      BinaryExpression: (node) => {
+        const matched = matchLengthComparison(node);
+
+        if (matched === undefined) return;
+
+        if (!isArrayLike(matched.arrayExpression)) return;
+
+        mut_nodesToFix.push({ node, ...matched });
+      },
+      'Program:exit': () => {
+        const hasSafeArrayImport =
+          getNamedImports(tsStdForgeImport).includes('SafeArray');
+
+        // The import fix lives on the first report only:
+        // `insertTextBefore(program, …)` produces overlapping ranges
+        // otherwise and only one of them would survive a pass. A first report
+        // silenced by an `eslint-disable` comment therefore takes the import
+        // with it.
+        for (const [
+          index,
+          { node, arrayExpression, guard },
+        ] of mut_nodesToFix.entries()) {
+          const arrayText = sourceCode.getText(arrayExpression);
+
+          context.report({
+            node,
+            messageId: MESSAGE_IDS[guard],
+            data: {
+              original: sourceCode.getText(node),
+              arrayName: arrayText,
+            },
+            fix: (fixer) => {
+              const replacement = `SafeArray.${guard}(${arrayText})`;
+
+              const importFixes =
+                index === 0 && !hasSafeArrayImport
+                  ? buildImportFixes(fixer, program, ['SafeArray'])
+                  : [];
+
+              return [...importFixes, fixer.replaceText(node, replacement)];
+            },
+          });
+        }
+      },
+    };
+  },
+  defaultOptions: [],
+} as const;
+
+/**
+ * Parses `<array>.length <op> <literal>` (in either operand order) into the
+ * array expression and the guard that replaces it, or `undefined` for anything
+ * else.
+ */
+const matchLengthComparison = (
+  // Deeply readonly here would make `lengthSide.object` a `DeepReadonly<...>`,
+  // which then needs an assertion to go back into the report queue.
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.BinaryExpression,
+):
+  | Readonly<{ arrayExpression: TSESTree.Expression; guard: Guard }>
+  | undefined => {
+  const { left, right } = node;
+
+  if (left.type === AST_NODE_TYPES.PrivateIdentifier) return undefined;
+
+  const lengthOnLeft = isLengthAccess(left);
+
+  const lengthSide = lengthOnLeft ? left : right;
+
+  const boundSide = lengthOnLeft ? right : left;
+
+  if (!isLengthAccess(lengthSide)) return undefined;
+
+  // `xs.length === ys.length` has `.length` on both sides and no literal
+  // bound, so the bound check below rejects it.
+  if (
+    boundSide.type !== AST_NODE_TYPES.Literal ||
+    typeof boundSide.value !== 'number'
+  ) {
+    return undefined;
+  }
+
+  const operator = lengthOnLeft ? node.operator : FLIPPED[node.operator];
+
+  const matched = COMPARISONS.find(
+    (entry) => entry.operator === operator && entry.bound === boundSide.value,
+  );
+
+  return matched === undefined
+    ? undefined
+    : { arrayExpression: lengthSide.object, guard: matched.guard };
+};
+
+const isLengthAccess = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Expression,
+): node is TSESTree.MemberExpression =>
+  node.type === AST_NODE_TYPES.MemberExpression &&
+  !node.computed &&
+  node.property.type === AST_NODE_TYPES.Identifier &&
+  node.property.name === 'length';

package/src/rules/prefer-safe-array-length-guard.test.mts

@@ -0,0 +1,152 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferSafeArrayLengthGuard } from './prefer-safe-array-length-guard.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      projectService: {
+        allowDefaultProject: ['*.ts*'],
+      },
+      tsconfigRootDir: `${import.meta.dirname}/../..`,
+    },
+  },
+});
+
+describe('prefer-safe-array-length-guard', () => {
+  tester.run('prefer-safe-array-length-guard', preferSafeArrayLengthGuard, {
+    valid: [
+      {
+        name: 'a string length check is not an array length check',
+        code: dedent`
+          declare const s: string;
+          const ok = s.length > 0;
+        `,
+      },
+      {
+        name: 'a bound with no named guard is left alone',
+        code: dedent`
+          declare const xs: readonly number[];
+          const ok = xs.length > 2;
+        `,
+      },
+      {
+        name: 'comparing two lengths is left alone',
+        code: dedent`
+          declare const xs: readonly number[];
+          declare const ys: readonly number[];
+          const ok = xs.length === ys.length;
+        `,
+      },
+      {
+        name: 'already using the guard',
+        code: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly number[];
+          const ok = SafeArray.isNonEmpty(xs);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'xs.length === 0 becomes isEmpty',
+        code: dedent`
+          declare const xs: readonly number[];
+          const ok = xs.length === 0;
+        `,
+        output: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly number[];
+          const ok = SafeArray.isEmpty(xs);
+        `,
+        errors: [{ messageId: 'useIsEmpty' }],
+      },
+      {
+        name: 'xs.length > 0 becomes isNonEmpty',
+        code: dedent`
+          declare const xs: readonly number[];
+          const ok = xs.length > 0;
+        `,
+        output: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly number[];
+          const ok = SafeArray.isNonEmpty(xs);
+        `,
+        errors: [{ messageId: 'useIsNonEmpty' }],
+      },
+      {
+        name: 'xs.length >= 1 becomes isNonEmpty',
+        code: dedent`
+          declare const xs: readonly number[];
+          const ok = xs.length >= 1;
+        `,
+        output: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly number[];
+          const ok = SafeArray.isNonEmpty(xs);
+        `,
+        errors: [{ messageId: 'useIsNonEmpty' }],
+      },
+      {
+        name: 'xs.length !== 0 becomes isNonEmpty',
+        code: dedent`
+          declare const xs: readonly number[];
+          const ok = xs.length !== 0;
+        `,
+        output: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly number[];
+          const ok = SafeArray.isNonEmpty(xs);
+        `,
+        errors: [{ messageId: 'useIsNonEmpty' }],
+      },
+      {
+        name: 'the operands the other way round are normalized',
+        code: dedent`
+          declare const xs: readonly number[];
+          const ok = 0 < xs.length;
+        `,
+        output: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly number[];
+          const ok = SafeArray.isNonEmpty(xs);
+        `,
+        errors: [{ messageId: 'useIsNonEmpty' }],
+      },
+      {
+        name: 'a tuple is an array too',
+        code: dedent`
+          declare const xs: readonly [number, number];
+          const ok = xs.length === 0;
+        `,
+        output: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly [number, number];
+          const ok = SafeArray.isEmpty(xs);
+        `,
+        errors: [{ messageId: 'useIsEmpty' }],
+      },
+      {
+        name: 'two checks in one file import once',
+        code: dedent`
+          declare const xs: readonly number[];
+          declare const ys: readonly number[];
+          const a = xs.length === 0;
+          const b = ys.length > 0;
+        `,
+        output: dedent`
+          import { SafeArray } from 'ts-std-forge';
+          declare const xs: readonly number[];
+          declare const ys: readonly number[];
+          const a = SafeArray.isEmpty(xs);
+          const b = SafeArray.isNonEmpty(ys);
+        `,
+        errors: [{ messageId: 'useIsEmpty' }, { messageId: 'useIsNonEmpty' }],
+      },
+    ],
+  });
+});

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

@@ -0,0 +1,162 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import * as ts from 'typescript';
+import {
+  buildImportFixes,
+  getNamedImports,
+  getTsStdForgeImport,
+} from './import-utils.mjs';
+
+type Options = readonly [];
+
+type MessageIds = 'useSafeNumberParseInteger';
+
+/**
+ * Returns `true` when every constituent of `type` is string-like, i.e. the
+ * type is assignable to the `string` parameter of `SafeNumber.parseInteger`.
+ * A union such as `string | undefined` is rejected so the autofix never
+ * produces a type error.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+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)
+  );
+};
+
+/**
+ * Detects `parseInt(x)` / `Number.parseInt(x, 10)` and replaces them with
+ * `Result.unwrapOkOr(SafeNumber.parseInteger(x), Number.NaN)` (ts-std-forge).
+ *
+ * Only base 10 is rewritten: `SafeNumber.parseInteger` takes no radix, so a
+ * call that passes another one means something the replacement cannot say.
+ */
+export const preferSafeNumberParseInteger: TSESLint.RuleModule<
+  MessageIds,
+  Options
+> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Replace `parseInt(x)` or `Number.parseInt(x, 10)` with `Result.unwrapOkOr(SafeNumber.parseInteger(x), Number.NaN)` from ts-std-forge.',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      useSafeNumberParseInteger:
+        'Replace `{{original}}` with `Result.unwrapOkOr(SafeNumber.parseInteger({{argName}}), Number.NaN)` from ts-std-forge.',
+    },
+  },
+
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+
+    const program = sourceCode.ast;
+
+    const tsStdForgeImport = getTsStdForgeImport(program);
+
+    const services = sourceCode.parserServices;
+
+    const mut_nodesToFix: {
+      node: TSESTree.CallExpression;
+      argExpression: TSESTree.Expression;
+    }[] = [];
+
+    return {
+      CallExpression: (node) => {
+        const { callee } = node;
+
+        // Match `parseInt(...)` or `Number.parseInt(...)`.
+        const isGlobalParseInt =
+          callee.type === AST_NODE_TYPES.Identifier &&
+          callee.name === 'parseInt';
+
+        const isNumberParseInt =
+          callee.type === AST_NODE_TYPES.MemberExpression &&
+          !callee.computed &&
+          callee.object.type === AST_NODE_TYPES.Identifier &&
+          callee.object.name === 'Number' &&
+          callee.property.type === AST_NODE_TYPES.Identifier &&
+          callee.property.name === 'parseInt';
+
+        if (!isGlobalParseInt && !isNumberParseInt) return;
+
+        const args = node.arguments;
+
+        const firstArg = args[0];
+
+        if (firstArg === undefined) return;
+
+        // Spread argument (`parseInt(...rest)`) cannot be rewritten safely.
+        if (firstArg.type === AST_NODE_TYPES.SpreadElement) return;
+
+        // Only base 10: accept a missing radix or an explicit literal `10`.
+        if (args.length >= 2) {
+          const radix = args[1];
+
+          if (radix?.type !== AST_NODE_TYPES.Literal || radix.value !== 10) {
+            return;
+          }
+        }
+
+        // The argument must be a `string` so the autofix is type-safe against
+        // `SafeNumber.parseInteger(value: string)`. Without type information,
+        // skip.
+        if (services?.program == null) return;
+
+        const checker = services.program.getTypeChecker();
+
+        const tsNode = services.esTreeNodeToTSNodeMap?.get(firstArg);
+
+        if (tsNode === undefined) return;
+
+        const argType = checker.getTypeAtLocation(tsNode);
+
+        if (!isStringType(argType)) return;
+
+        mut_nodesToFix.push({ node, argExpression: firstArg });
+      },
+      'Program:exit': () => {
+        const namedImports = getNamedImports(tsStdForgeImport);
+
+        const missingImports = (['Result', 'SafeNumber'] as const).filter(
+          (name) => !namedImports.includes(name),
+        );
+
+        for (const [
+          index,
+          { node, argExpression },
+        ] of mut_nodesToFix.entries()) {
+          const argText = sourceCode.getText(argExpression);
+
+          context.report({
+            node,
+            messageId: 'useSafeNumberParseInteger',
+            data: {
+              original: sourceCode.getText(node),
+              argName: argText,
+            },
+            fix: (fixer) => {
+              const core = `Result.unwrapOkOr(SafeNumber.parseInteger(${argText}), Number.NaN)`;
+
+              const importFixes =
+                index === 0 && missingImports.length > 0
+                  ? buildImportFixes(fixer, program, missingImports)
+                  : [];
+
+              return [...importFixes, fixer.replaceText(node, core)];
+            },
+          });
+        }
+      },
+    };
+  },
+  defaultOptions: [],
+} as const;

package/src/rules/prefer-safe-number-parse-integer.test.mts

@@ -0,0 +1,67 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferSafeNumberParseInteger } from './prefer-safe-number-parse-integer.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      projectService: {
+        allowDefaultProject: ['*.ts*'],
+      },
+      tsconfigRootDir: `${import.meta.dirname}/../..`,
+    },
+  },
+});
+
+describe('prefer-safe-number-parse-integer', () => {
+  tester.run('prefer-safe-number-parse-integer', preferSafeNumberParseInteger, {
+    valid: [
+      {
+        name: 'ignores a radix other than 10',
+        code: dedent`
+          declare const s: string;
+          const n = parseInt(s, 16);
+        `,
+      },
+      {
+        name: 'ignores a non-string argument',
+        code: dedent`
+          declare const x: number;
+          const n = parseInt(x as unknown as string & never, 10);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'rewrites parseInt without a radix',
+        code: dedent`
+          declare const s: string;
+          const n = parseInt(s);
+        `,
+        output: dedent`
+          import { Result, SafeNumber } from 'ts-std-forge';
+          declare const s: string;
+          const n = Result.unwrapOkOr(SafeNumber.parseInteger(s), Number.NaN);
+        `,
+        errors: [{ messageId: 'useSafeNumberParseInteger' }],
+      },
+      {
+        name: 'rewrites Number.parseInt(x, 10)',
+        code: dedent`
+          declare const s: string;
+          const n = Number.parseInt(s, 10);
+        `,
+        output: dedent`
+          import { Result, SafeNumber } from 'ts-std-forge';
+          declare const s: string;
+          const n = Result.unwrapOkOr(SafeNumber.parseInteger(s), Number.NaN);
+        `,
+        errors: [{ messageId: 'useSafeNumberParseInteger' }],
+      },
+    ],
+  });
+});