eslint-plugin-ts-data-forge 0.1.0

package/src/rules/prefer-comparison-over-nullish-guard.mts

@@ -0,0 +1,141 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { type DeepReadonly } from 'ts-type-forge';
+import { buildCalleeResolver, getTsDataForgeImport } from './import-utils.mjs';
+
+type Options = readonly [];
+
+type MessageIds = 'preferComparison';
+
+type ComparisonSpec = Readonly<{
+  op: '!==' | '===';
+  literal: 'null' | 'undefined';
+}>;
+
+/**
+ * The nullish guards that are meant for point-free use (e.g.
+ * `xs.filter(isNotUndefined)`). When called with an explicit argument a direct
+ * comparison is clearer, so map each to its equivalent operator and literal.
+ */
+const COMPARISON_GUARDS: DeepReadonly<Record<string, ComparisonSpec>> = {
+  isUndefined: { op: '===', literal: 'undefined' },
+  isNotUndefined: { op: '!==', literal: 'undefined' },
+  isNull: { op: '===', literal: 'null' },
+  isNotNull: { op: '!==', literal: 'null' },
+} as const;
+
+/**
+ * Argument expression kinds whose precedence is lower than equality, so they
+ * must be parenthesized when placed on the left of `===` / `!==`.
+ */
+const ARG_NEEDS_PARENS: ReadonlySet<string> = new Set([
+  AST_NODE_TYPES.LogicalExpression,
+  AST_NODE_TYPES.ConditionalExpression,
+  AST_NODE_TYPES.AssignmentExpression,
+  AST_NODE_TYPES.SequenceExpression,
+  AST_NODE_TYPES.ArrowFunctionExpression,
+  AST_NODE_TYPES.YieldExpression,
+]);
+
+/**
+ * Returns `true` when the comparison must be wrapped in parentheses to preserve
+ * the original grouping given the call expression's parent context.
+ */
+const needsWrappingInParent = (
+  node: DeepReadonly<TSESTree.CallExpression>,
+): boolean => {
+  const { parent } = node;
+
+  // `parent.type` is one of 130+ AST kinds; only a handful need wrapping.
+  // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
+  switch (parent.type) {
+    case AST_NODE_TYPES.UnaryExpression:
+    case AST_NODE_TYPES.AwaitExpression:
+    case AST_NODE_TYPES.BinaryExpression:
+    case AST_NODE_TYPES.TSNonNullExpression:
+      return true;
+
+    case AST_NODE_TYPES.MemberExpression:
+      return parent.object === node;
+
+    case AST_NODE_TYPES.CallExpression:
+    case AST_NODE_TYPES.NewExpression:
+      return parent.callee === node;
+
+    default:
+      return false;
+  }
+};
+
+export const preferComparisonOverNullishGuard: TSESLint.RuleModule<
+  MessageIds,
+  Options
+> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer a direct `=== null` / `!== undefined` comparison over calling `isNull`, `isNotNull`, `isUndefined`, or `isNotUndefined` with an explicit argument (those guards are intended for point-free use such as `xs.filter(isNotUndefined)`).',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      preferComparison:
+        'Prefer `{{comparison}}` over calling `{{name}}` with an explicit argument.',
+    },
+  },
+
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+
+    const resolveGuard = buildCalleeResolver(
+      getTsDataForgeImport(sourceCode.ast),
+    );
+
+    return {
+      CallExpression: (node) => {
+        if (node.arguments.length !== 1) return;
+
+        const argument = node.arguments[0];
+
+        if (
+          argument === undefined ||
+          argument.type === AST_NODE_TYPES.SpreadElement
+        ) {
+          return;
+        }
+
+        const resolved = resolveGuard(node.callee);
+
+        if (resolved === undefined) return;
+
+        const spec = COMPARISON_GUARDS[resolved.canonicalName];
+
+        if (spec === undefined) return;
+
+        const argRaw = sourceCode.getText(argument);
+
+        const argText = ARG_NEEDS_PARENS.has(argument.type)
+          ? `(${argRaw})`
+          : argRaw;
+
+        const comparison = `${argText} ${spec.op} ${spec.literal}`;
+
+        const replacement = needsWrappingInParent(node)
+          ? `(${comparison})`
+          : comparison;
+
+        context.report({
+          node,
+          messageId: 'preferComparison',
+          data: { comparison, name: resolved.canonicalName },
+          fix: (fixer) => fixer.replaceText(node, replacement),
+        });
+      },
+    };
+  },
+  defaultOptions: [],
+} as const;

package/src/rules/prefer-comparison-over-nullish-guard.test.mts

@@ -0,0 +1,171 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferComparisonOverNullishGuard } from './prefer-comparison-over-nullish-guard.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      projectService: {
+        allowDefaultProject: ['*.ts*'],
+      },
+      tsconfigRootDir: `${import.meta.dirname}/../..`,
+    },
+  },
+});
+
+describe('prefer-comparison-over-nullish-guard', () => {
+  tester.run(
+    'prefer-comparison-over-nullish-guard',
+    preferComparisonOverNullishGuard,
+    {
+      valid: [
+        {
+          name: 'point-free usage is allowed',
+          code: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const xs: readonly (string | undefined)[];
+            const ys = xs.filter(isNotUndefined);
+          `,
+        },
+        {
+          name: 'other ts-data-forge guards are not affected',
+          code: dedent`
+            import { isNonNullish } from 'ts-data-forge';
+            declare const x: string | null | undefined;
+            const y = isNonNullish(x);
+          `,
+        },
+        {
+          name: 'same-named function not imported from ts-data-forge',
+          code: dedent`
+            const isNotUndefined = (u: unknown): boolean => u !== undefined;
+            declare const x: string | undefined;
+            const y = isNotUndefined(x);
+          `,
+        },
+      ],
+      invalid: [
+        {
+          name: 'isNotUndefined with explicit argument',
+          code: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = isNotUndefined(x);
+          `,
+          output: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = x !== undefined;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'isUndefined with explicit argument',
+          code: dedent`
+            import { isUndefined } from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = isUndefined(x);
+          `,
+          output: dedent`
+            import { isUndefined } from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = x === undefined;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'isNull with explicit argument',
+          code: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const x: string | null;
+            const y = isNull(x);
+          `,
+          output: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const x: string | null;
+            const y = x === null;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'isNotNull inside a logical expression (no extra parens)',
+          code: dedent`
+            import { isNotNull } from 'ts-data-forge';
+            declare const x: string | null;
+            const y = isNotNull(x) && x.length > 0;
+          `,
+          output: dedent`
+            import { isNotNull } from 'ts-data-forge';
+            declare const x: string | null;
+            const y = x !== null && x.length > 0;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'negated call is wrapped in parentheses',
+          code: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = !isNotUndefined(x);
+          `,
+          output: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = !(x !== undefined);
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'member-access argument',
+          code: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const obj: { value: string | undefined };
+            const y = isNotUndefined(obj.value);
+          `,
+          output: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const obj: { value: string | undefined };
+            const y = obj.value !== undefined;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'low-precedence argument is parenthesized',
+          code: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const a: string | undefined;
+            declare const b: string | undefined;
+            declare const cond: boolean;
+            const y = isNotUndefined(cond ? a : b);
+          `,
+          output: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const a: string | undefined;
+            declare const b: string | undefined;
+            declare const cond: boolean;
+            const y = (cond ? a : b) !== undefined;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'namespace import member call',
+          code: dedent`
+            import * as tf from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = tf.isNotUndefined(x);
+          `,
+          output: dedent`
+            import * as tf from 'ts-data-forge';
+            declare const x: string | undefined;
+            const y = x !== undefined;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+      ],
+    },
+  );
+});

package/src/rules/prefer-is-non-null-object.mts

@@ -0,0 +1,145 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { type DeepReadonly } from 'ts-type-forge';
+import {
+  buildImportFixes,
+  getNamedImports,
+  getTsDataForgeImport,
+} from './import-utils.mjs';
+
+type Options = readonly [];
+
+type MessageIds = 'useIsNonNullObject';
+
+export const preferIsNonNullObject: TSESLint.RuleModule<MessageIds, Options> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Replace `typeof u === "object" && u !== null` with `isNonNullObject(u)` from ts-data-forge.',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      useIsNonNullObject:
+        'Replace the object/null check with `isNonNullObject()` from ts-data-forge.',
+    },
+  },
+
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+
+    const program = sourceCode.ast;
+
+    const tsDataForgeImport = getTsDataForgeImport(program);
+
+    const mut_nodesToFix: {
+      node: TSESTree.LogicalExpression;
+      identifierName: string;
+    }[] = [];
+
+    return {
+      LogicalExpression: (node) => {
+        const identifierName = getNonNullObjectIdentifierName(node);
+
+        if (identifierName === undefined) return;
+
+        mut_nodesToFix.push({ node, identifierName });
+      },
+      'Program:exit': () => {
+        // Check if isNonNullObject is already imported
+        const hasIsNonNullObjectImport =
+          getNamedImports(tsDataForgeImport).includes('isNonNullObject');
+
+        // Note: We add import only for the first node to avoid conflicts when
+        // multiple fixes try to insert at the same position. This means if the
+        // first node is disabled via eslint-disable comment, no import will be
+        // added.
+        for (const [
+          index,
+          { node, identifierName },
+        ] of mut_nodesToFix.entries()) {
+          context.report({
+            node,
+            messageId: 'useIsNonNullObject',
+            fix: (fixer) => {
+              const replacement = `isNonNullObject(${identifierName})`;
+
+              // Add import only for the first node and only if not already imported
+              const importFixes =
+                index === 0 && !hasIsNonNullObjectImport
+                  ? buildImportFixes(fixer, program, tsDataForgeImport, [
+                      'isNonNullObject',
+                    ])
+                  : [];
+
+              return [...importFixes, fixer.replaceText(node, replacement)];
+            },
+          });
+        }
+      },
+    };
+  },
+  defaultOptions: [],
+} as const;
+
+const getNonNullObjectIdentifierName = (
+  node: DeepReadonly<TSESTree.LogicalExpression>,
+): string | undefined => {
+  if (node.operator !== '&&') return undefined;
+
+  const leftIdentifierName = getTypeofObjectIdentifierName(node.left);
+
+  const rightIdentifierName = getNonNullCheckIdentifierName(node.right);
+
+  if (leftIdentifierName === undefined) return undefined;
+
+  if (rightIdentifierName === undefined) return undefined;
+
+  if (leftIdentifierName !== rightIdentifierName) return undefined;
+
+  return leftIdentifierName;
+};
+
+const getTypeofObjectIdentifierName = (
+  node: DeepReadonly<TSESTree.Expression>,
+): string | undefined => {
+  if (node.type !== AST_NODE_TYPES.BinaryExpression) return undefined;
+
+  if (node.operator !== '===') return undefined;
+
+  const { left, right } = node;
+
+  if (left.type !== AST_NODE_TYPES.UnaryExpression) return undefined;
+
+  if (left.operator !== 'typeof') return undefined;
+
+  if (right.type !== AST_NODE_TYPES.Literal) return undefined;
+
+  if (right.value !== 'object') return undefined;
+
+  if (left.argument.type !== AST_NODE_TYPES.Identifier) return undefined;
+
+  return left.argument.name;
+};
+
+const getNonNullCheckIdentifierName = (
+  node: DeepReadonly<TSESTree.Expression>,
+): string | undefined => {
+  if (node.type !== AST_NODE_TYPES.BinaryExpression) return undefined;
+
+  if (node.operator !== '!==') return undefined;
+
+  const { left, right } = node;
+
+  if (left.type !== AST_NODE_TYPES.Identifier) return undefined;
+
+  if (right.type !== AST_NODE_TYPES.Literal) return undefined;
+
+  if (right.value !== null) return undefined;
+
+  return left.name;
+};

package/src/rules/prefer-is-non-null-object.test.mts

@@ -0,0 +1,156 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferIsNonNullObject } from './prefer-is-non-null-object.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      projectService: {
+        allowDefaultProject: ['*.ts*'],
+      },
+      tsconfigRootDir: `${import.meta.dirname}/../..`,
+    },
+  },
+});
+
+describe('prefer-is-non-null-object', () => {
+  tester.run('prefer-is-non-null-object', preferIsNonNullObject, {
+    valid: [
+      {
+        name: 'ignores non-matching typeof checks',
+        code: dedent`
+          const u = {};
+          const ok = typeof u === "object" && v !== null;
+        `,
+      },
+    ],
+    invalid: [
+      ...([
+        {
+          name: 'replaces typeof object check with isNonNullObject import',
+          code: dedent`
+            const u = {};
+            const ok = typeof u === "object" && u !== null;
+          `,
+          output: dedent`
+            import { isNonNullObject } from 'ts-data-forge';
+            const u = {};
+            const ok = isNonNullObject(u);
+          `,
+          errors: [{ messageId: 'useIsNonNullObject' }],
+        },
+        {
+          name: 'replaces typeof object check with isNonNullObject import when other imports exist',
+          code: dedent`
+            import { noop } from './noop.mjs';
+
+            const u = {};
+            noop(typeof u === "object" && u !== null);
+          `,
+          output: dedent`
+            import { isNonNullObject } from 'ts-data-forge';
+            import { noop } from './noop.mjs';
+
+            const u = {};
+            noop(isNonNullObject(u));
+          `,
+          errors: [{ messageId: 'useIsNonNullObject' }],
+        },
+        {
+          name: 'replaces multiple typeof object checks with isNonNullObject imports',
+          code: dedent`
+            const u = {};
+            const ok = typeof u === "object" && u !== null;
+            const ok2 = typeof u === "object" && u !== null;
+          `,
+          output: dedent`
+            import { isNonNullObject } from 'ts-data-forge';
+            const u = {};
+            const ok = isNonNullObject(u);
+            const ok2 = isNonNullObject(u);
+          `,
+          errors: [
+            { messageId: 'useIsNonNullObject' },
+            { messageId: 'useIsNonNullObject' },
+          ],
+        },
+      ] as const),
+
+      ...([
+        {
+          name: 'keeps existing isNonNullObject import',
+          code: dedent`
+            import { isNonNullObject } from 'ts-data-forge';
+
+            const ok = typeof u === "object" && u !== null;
+          `,
+          output: dedent`
+            import { isNonNullObject } from 'ts-data-forge';
+
+            const ok = isNonNullObject(u);
+          `,
+          errors: [{ messageId: 'useIsNonNullObject' }],
+        },
+        {
+          name: 'keeps existing isNonNullObject import when other imports exist',
+          code: dedent`
+            import { noop } from './noop.mjs';
+            import { isNonNullObject } from 'ts-data-forge';
+
+            const u = {};
+            noop(typeof u === "object" && u !== null);
+          `,
+          output: dedent`
+            import { noop } from './noop.mjs';
+            import { isNonNullObject } from 'ts-data-forge';
+
+            const u = {};
+            noop(isNonNullObject(u));
+          `,
+          errors: [{ messageId: 'useIsNonNullObject' }],
+        },
+      ] as const),
+
+      ...([
+        {
+          name: 'adds import even if ts-data-forge import exists',
+          code: dedent`
+            import { asInt } from 'ts-data-forge';
+
+            const ok = typeof u === "object" && u !== null;
+          `,
+          output: dedent`
+            import { isNonNullObject } from 'ts-data-forge';
+            import { asInt } from 'ts-data-forge';
+
+            const ok = isNonNullObject(u);
+          `,
+          errors: [{ messageId: 'useIsNonNullObject' }],
+        },
+        {
+          name: 'adds import even if ts-data-forge import exists (with other imports)',
+          code: dedent`
+            import { noop } from './noop.mjs';
+            import { asInt } from 'ts-data-forge';
+
+            const u = {};
+            noop(typeof u === "object" && u !== null);
+          `,
+          output: dedent`
+            import { isNonNullObject } from 'ts-data-forge';
+            import { noop } from './noop.mjs';
+            import { asInt } from 'ts-data-forge';
+
+            const u = {};
+            noop(isNonNullObject(u));
+          `,
+          errors: [{ messageId: 'useIsNonNullObject' }],
+        },
+      ] as const),
+    ],
+  });
+}, 20000);