eslint-plugin-ts-std-forge 0.1.0

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

@@ -0,0 +1,142 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { type DeepReadonly } from 'ts-type-forge';
+import {
+  buildImportFixes,
+  getNamedImports,
+  getTsStdForgeImport,
+} 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-std-forge.',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      useIsNonNullObject:
+        'Replace the object/null check with `isNonNullObject()` from ts-std-forge.',
+    },
+  },
+
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+
+    const program = sourceCode.ast;
+
+    const tsStdForgeImport = getTsStdForgeImport(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': () => {
+        const hasIsNonNullObjectImport =
+          getNamedImports(tsStdForgeImport).includes('isNonNullObject');
+
+        // 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, identifierName },
+        ] of mut_nodesToFix.entries()) {
+          context.report({
+            node,
+            messageId: 'useIsNonNullObject',
+            fix: (fixer) => {
+              const replacement = `isNonNullObject(${identifierName})`;
+
+              const importFixes =
+                index === 0 && !hasIsNonNullObjectImport
+                  ? buildImportFixes(fixer, program, ['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,54 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferIsNonNullObject } from './prefer-is-non-null-object.mjs';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('prefer-is-non-null-object', preferIsNonNullObject, {
+  valid: [
+    {
+      name: 'Already using isNonNullObject',
+      code: dedent`
+        import { isNonNullObject } from 'ts-std-forge';
+        const ok = isNonNullObject(u);
+      `,
+    },
+    {
+      name: 'The two halves are about different identifiers',
+      code: dedent`
+        const ok = typeof u === 'object' && v !== null;
+      `,
+    },
+    {
+      name: 'Not an object check',
+      code: dedent`
+        const ok = typeof u === 'string' && u !== null;
+      `,
+    },
+  ],
+  invalid: [
+    {
+      name: 'Replace the object/null check',
+      code: dedent`
+        const ok = typeof u === 'object' && u !== null;
+      `,
+      output: dedent`
+        import { isNonNullObject } from 'ts-std-forge';
+        const ok = isNonNullObject(u);
+      `,
+      errors: [{ messageId: 'useIsNonNullObject' }],
+    },
+    {
+      name: 'Reuses an existing import',
+      code: dedent`
+        import { isNonNullObject } from 'ts-std-forge';
+        const ok = typeof u === 'object' && u !== null;
+      `,
+      output: dedent`
+        import { isNonNullObject } from 'ts-std-forge';
+        const ok = isNonNullObject(u);
+      `,
+      errors: [{ messageId: 'useIsNonNullObject' }],
+    },
+  ],
+});

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

@@ -0,0 +1,217 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { SafeArray } from 'ts-std-forge';
+import * as ts from 'typescript';
+import {
+  buildImportFixes,
+  getNamedImports,
+  getTsStdForgeImport,
+} from './import-utils.mjs';
+
+type Options = readonly [];
+
+type MessageIds = 'useIsRecordAndHasKey' | 'useHasKey';
+
+export const preferIsRecordAndHasKey: TSESLint.RuleModule<MessageIds, Options> =
+  {
+    meta: {
+      type: 'suggestion',
+      docs: {
+        description:
+          'Replace `Object.hasOwn(obj, key)` or `key in obj` with `isRecord(obj) && hasKey(obj, key)` from ts-std-forge',
+      },
+      fixable: 'code',
+      schema: [],
+      messages: {
+        useIsRecordAndHasKey:
+          'Replace `{{original}}` with `isRecord({{objName}}) && hasKey({{objName}}, {{keyName}})` from ts-std-forge.',
+        useHasKey:
+          'Replace `{{original}}` with `hasKey({{objName}}, {{keyName}})` from ts-std-forge.',
+      },
+    },
+
+    create: (context) => {
+      const sourceCode = context.sourceCode;
+
+      const program = sourceCode.ast;
+
+      const tsStdForgeImport = getTsStdForgeImport(program);
+
+      const services = sourceCode.parserServices;
+
+      const checker = services?.program?.getTypeChecker();
+
+      /**
+       * Whether the `isRecord(...)` half of the rewrite would be dead code
+       * because the object already satisfies `hasKey`'s
+       * `R extends UnknownRecord` constraint. 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 => {
+        if (checker === undefined) return false;
+
+        const tsNode = services?.esTreeNodeToTSNodeMap?.get(expression);
+
+        return (
+          tsNode !== undefined &&
+          isAlreadyRecordType(checker, checker.getTypeAtLocation(tsNode))
+        );
+      };
+
+      const mut_nodesToFix: {
+        node: TSESTree.CallExpression | TSESTree.BinaryExpression;
+        objExpression: TSESTree.Expression;
+        keyExpression: TSESTree.Expression;
+      }[] = [];
+
+      return {
+        // Handle Object.hasOwn(obj, key)
+        CallExpression: (node) => {
+          if (
+            node.callee.type !== AST_NODE_TYPES.MemberExpression ||
+            node.callee.object.type !== AST_NODE_TYPES.Identifier ||
+            node.callee.object.name !== 'Object' ||
+            node.callee.property.type !== AST_NODE_TYPES.Identifier ||
+            node.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
+          ) {
+            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) return;
+
+          mut_nodesToFix.push({
+            node,
+            objExpression,
+            keyExpression,
+          });
+        },
+
+        'Program:exit': () => {
+          const namedImports = getNamedImports(tsStdForgeImport);
+
+          const rewrites = mut_nodesToFix.map((entry) => ({
+            ...entry,
+            // A record-typed object makes the `isRecord(...)` conjunct always
+            // true, so it is left out of the replacement entirely.
+            needsIsRecord: !isKnownRecord(entry.objExpression),
+          }));
+
+          const importsToAdd: readonly string[] = [
+            ...(rewrites.some(({ needsIsRecord }) => needsIsRecord) &&
+            !namedImports.includes('isRecord')
+              ? ['isRecord']
+              : []),
+            ...(namedImports.includes('hasKey') ? [] : ['hasKey']),
+          ];
+
+          for (const [
+            index,
+            { node, objExpression, keyExpression, needsIsRecord },
+          ] of rewrites.entries()) {
+            const objText = sourceCode.getText(objExpression);
+
+            const keyText = sourceCode.getText(keyExpression);
+
+            const originalText = sourceCode.getText(node);
+
+            context.report({
+              node,
+              messageId: needsIsRecord ? 'useIsRecordAndHasKey' : 'useHasKey',
+              data: {
+                original: originalText,
+                objName: objText,
+                keyName: keyText,
+              },
+              fix: (fixer) => {
+                const replacement = needsIsRecord
+                  ? `(isRecord(${objText}) && hasKey(${objText}, ${keyText}))`
+                  : `hasKey(${objText}, ${keyText})`;
+
+                // All import fixes have to live on the first report:
+                // `insertTextBefore(program, …)` produces overlapping ranges
+                // otherwise and only one of them would survive a pass.
+                const importFixes =
+                  index === 0 && importsToAdd.length > 0
+                    ? buildImportFixes(fixer, program, importsToAdd)
+                    : [];
+
+                return [...importFixes, fixer.replaceText(node, replacement)];
+              },
+            });
+          }
+        },
+      };
+    },
+    defaultOptions: [],
+  } as const;
+
+/**
+ * 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 &&
+      SafeArray.isEmpty(
+        checker.getSignaturesOfType(type, ts.SignatureKind.Call),
+      ) &&
+      SafeArray.isEmpty(
+        checker.getSignaturesOfType(type, ts.SignatureKind.Construct),
+      ) &&
+      !checker.isArrayType(type) &&
+      !checker.isTupleType(type);

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

@@ -0,0 +1,80 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferIsRecordAndHasKey } from './prefer-is-record-and-has-key.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      projectService: {
+        allowDefaultProject: ['*.ts*'],
+      },
+      tsconfigRootDir: `${import.meta.dirname}/../..`,
+    },
+  },
+});
+
+describe('prefer-is-record-and-has-key', () => {
+  tester.run('prefer-is-record-and-has-key', preferIsRecordAndHasKey, {
+    valid: [
+      {
+        name: 'ignores other Object methods',
+        code: dedent`
+          const obj = { a: 1 };
+          const keys = Object.keys(obj);
+        `,
+      },
+      {
+        name: 'ignores hasOwn with the wrong number of arguments',
+        code: dedent`
+          const obj = { a: 1 };
+          const ok = Object.hasOwn(obj);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'rewrites Object.hasOwn on an unknown object, keeping isRecord',
+        code: dedent`
+          declare const obj: unknown;
+          const ok = Object.hasOwn(obj, 'a');
+        `,
+        output: dedent`
+          import { isRecord, hasKey } from 'ts-std-forge';
+          declare const obj: unknown;
+          const ok = (isRecord(obj) && hasKey(obj, 'a'));
+        `,
+        errors: [{ messageId: 'useIsRecordAndHasKey' }],
+      },
+      {
+        name: 'drops isRecord when the object already has a string index signature',
+        code: dedent`
+          declare const obj: Readonly<Record<string, unknown>>;
+          const ok = Object.hasOwn(obj, 'a');
+        `,
+        output: dedent`
+          import { hasKey } from 'ts-std-forge';
+          declare const obj: Readonly<Record<string, unknown>>;
+          const ok = hasKey(obj, 'a');
+        `,
+        errors: [{ messageId: 'useHasKey' }],
+      },
+      {
+        name: 'rewrites `key in obj` too',
+        code: dedent`
+          declare const obj: Record<string, number>;
+          const ok = 'a' in obj;
+        `,
+        output: dedent`
+          import { hasKey } from 'ts-std-forge';
+          declare const obj: Record<string, number>;
+          const ok = hasKey(obj, 'a');
+        `,
+        errors: [{ messageId: 'useHasKey' }],
+      },
+    ],
+  });
+});

package/src/rules/prefer-safe-array-is-array.mts

@@ -0,0 +1,99 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { type DeepReadonly } from 'ts-type-forge';
+import {
+  buildImportFixes,
+  getNamedImports,
+  getTsStdForgeImport,
+} from './import-utils.mjs';
+
+type Options = readonly [];
+
+type MessageIds = 'useSafeArrayIsArray';
+
+export const preferSafeArrayIsArray: TSESLint.RuleModule<MessageIds, Options> =
+  {
+    meta: {
+      type: 'suggestion',
+      docs: {
+        description:
+          'Replace `Array.isArray` with `SafeArray.isArray` from ts-std-forge.',
+      },
+      fixable: 'code',
+      schema: [],
+      messages: {
+        useSafeArrayIsArray:
+          'Replace `Array.isArray` with `SafeArray.isArray` from ts-std-forge.',
+      },
+    },
+
+    create: (context) => {
+      const sourceCode = context.sourceCode;
+
+      const program = sourceCode.ast;
+
+      const tsStdForgeImport = getTsStdForgeImport(program);
+
+      const mut_nodesToFix: TSESTree.CallExpression[] = [];
+
+      return {
+        CallExpression: (node) => {
+          if (!isArrayIsArrayCall(node)) return;
+
+          mut_nodesToFix.push(node);
+        },
+        '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] of mut_nodesToFix.entries()) {
+            context.report({
+              node,
+              messageId: 'useSafeArrayIsArray',
+              fix: (fixer) => {
+                const callee = node.callee;
+
+                if (callee.type !== AST_NODE_TYPES.MemberExpression) return [];
+
+                const replacement = `SafeArray.isArray${sourceCode.getText(node).slice(sourceCode.getText(callee).length)}`;
+
+                const importFixes =
+                  index === 0 && !hasSafeArrayImport
+                    ? buildImportFixes(fixer, program, ['SafeArray'])
+                    : [];
+
+                return [...importFixes, fixer.replaceText(node, replacement)];
+              },
+            });
+          }
+        },
+      };
+    },
+    defaultOptions: [],
+  } as const;
+
+const isArrayIsArrayCall = (
+  node: DeepReadonly<TSESTree.CallExpression>,
+): boolean => {
+  if (node.callee.type !== AST_NODE_TYPES.MemberExpression) return false;
+
+  const { object, property } = node.callee;
+
+  if (object.type !== AST_NODE_TYPES.Identifier) return false;
+
+  if (object.name !== 'Array') return false;
+
+  if (property.type !== AST_NODE_TYPES.Identifier) return false;
+
+  if (property.name !== 'isArray') return false;
+
+  return true;
+};

package/src/rules/prefer-safe-array-is-array.test.mts

@@ -0,0 +1,65 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferSafeArrayIsArray } from './prefer-safe-array-is-array.mjs';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('prefer-safe-array-is-array', preferSafeArrayIsArray, {
+  valid: [
+    {
+      name: 'Already using SafeArray.isArray',
+      code: dedent`
+        import { SafeArray } from 'ts-std-forge';
+        const result = SafeArray.isArray(value);
+      `,
+    },
+    {
+      name: 'Not Array.isArray call',
+      code: dedent`
+        const obj = { isArray: () => true };
+        const result = obj.isArray(value);
+      `,
+    },
+  ],
+  invalid: [
+    {
+      name: 'Replace Array.isArray with SafeArray.isArray',
+      code: dedent`
+        const result = Array.isArray(value);
+      `,
+      output: dedent`
+        import { SafeArray } from 'ts-std-forge';
+        const result = SafeArray.isArray(value);
+      `,
+      errors: [{ messageId: 'useSafeArrayIsArray' }],
+    },
+    {
+      name: 'Replace Array.isArray when SafeArray is already imported',
+      code: dedent`
+        import { SafeArray } from 'ts-std-forge';
+        const result = Array.isArray(value);
+      `,
+      output: dedent`
+        import { SafeArray } from 'ts-std-forge';
+        const result = SafeArray.isArray(value);
+      `,
+      errors: [{ messageId: 'useSafeArrayIsArray' }],
+    },
+    {
+      name: 'Replace multiple Array.isArray calls, importing once',
+      code: dedent`
+        const result1 = Array.isArray(value1);
+        const result2 = Array.isArray(value2);
+      `,
+      output: dedent`
+        import { SafeArray } from 'ts-std-forge';
+        const result1 = SafeArray.isArray(value1);
+        const result2 = SafeArray.isArray(value2);
+      `,
+      errors: [
+        { messageId: 'useSafeArrayIsArray' },
+        { messageId: 'useSafeArrayIsArray' },
+      ],
+    },
+  ],
+});