eslint-plugin-ts-data-forge 0.1.7 → 0.3.0

package/src/rules/prefer-canonical-length-guard.mts

@@ -0,0 +1,250 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { getImportedLocalName, getTsDataForgeImport } from './import-utils.mjs';
+import { preferArrIsBoundedLengthArray } from './prefer-arr-is-bounded-length-array.mjs';
+import { preferArrIsFixedLengthArray } from './prefer-arr-is-fixed-length-array.mjs';
+import { preferArrIsMaxLengthArray } from './prefer-arr-is-max-length-array.mjs';
+import { preferArrIsMinLengthArray } from './prefer-arr-is-min-length-array.mjs';
+import { preferArrIsNonEmpty } from './prefer-arr-is-non-empty.mjs';
+
+type Options = readonly [];
+
+type MessageIds =
+  | 'useCanonicalGuard'
+  | 'useIsBoundedLengthArray'
+  | 'useIsFixedLengthArray'
+  | 'useIsMaxLengthArray'
+  | 'useIsMinLengthArray'
+  | 'useIsNonEmpty';
+
+/**
+ * The `xs.length <op> n` → `Arr.is*` rules folded into this one.
+ *
+ * Their implementations are reused as-is rather than rewritten: this rule
+ * merges their visitors, so every case they already cover (type-aware array
+ * checks, `Arr` import insertion, the `&&`-bounded-range special case) keeps
+ * behaving exactly as before, and their co-located tests keep exercising them
+ * directly.
+ */
+const COMPARISON_RULES = [
+  preferArrIsNonEmpty,
+  preferArrIsMinLengthArray,
+  preferArrIsMaxLengthArray,
+  preferArrIsBoundedLengthArray,
+  preferArrIsFixedLengthArray,
+] as const;
+
+const MESSAGES = {
+  useCanonicalGuard:
+    'Replace `{{arrName}}.{{guard}}({{boundsText}})` with `{{arrName}}.{{replacement}}(...)`: the bound makes the two guards equivalent.',
+  useIsNonEmpty: preferArrIsNonEmpty.meta.messages.useIsNonEmpty,
+  useIsMinLengthArray:
+    preferArrIsMinLengthArray.meta.messages.useIsMinLengthArray,
+  useIsMaxLengthArray:
+    preferArrIsMaxLengthArray.meta.messages.useIsMaxLengthArray,
+  useIsBoundedLengthArray:
+    preferArrIsBoundedLengthArray.meta.messages.useIsBoundedLengthArray,
+  useIsFixedLengthArray:
+    preferArrIsFixedLengthArray.meta.messages.useIsFixedLengthArray,
+} as const satisfies Record<MessageIds, string>;
+
+/**
+ * Length guards whose bound makes them redundant with a named degenerate
+ * guard, keyed by guard name.
+ *
+ * Every entry stays inside its own family rather than crossing the
+ * branded/structural divide:
+ *
+ * - the branded `*Array` guards go to `isEmpty` / `isNonEmpty`, which narrow to
+ *   `FixedLengthArray<0, E> & Xs` / `MinLengthArray<1, E> & Xs`;
+ * - the structural `*Tuple` guards go to `isEmptyTuple` / `isNonEmptyTuple`,
+ *   which narrow to `readonly []` / `MinLengthTuple<1, E>`.
+ *
+ * Most entries are then **type-identical** — `isFixedLengthArray(0, xs)` and
+ * `isMinLengthArray(1, xs)` produce exactly what `isEmpty` / `isNonEmpty`
+ * narrow to, and `FixedLengthTuple<0, E>`, `MaxLengthTuple<0, E>` and
+ * `BoundedLengthTuple<0, 0, E>` are all `readonly []`. Two *strengthen*:
+ * `MaxLengthArray<0, E>` and `BoundedLengthArray<0, 0, E>` do not include the
+ * `readonly []` structural part that `FixedLengthArray<0, E>` intersects on, so
+ * rewriting them to `isEmpty` adds it. That is sound for a guard — the narrowed
+ * type only flows outwards, and the stronger type is assignable everywhere the
+ * old one was — and it stays within the branded family.
+ *
+ * Sending a `*Tuple` guard to the branded `isEmpty` would also be sound, but it
+ * would silently change which family the value belongs to, which is why each
+ * family keeps its own lane.
+ */
+const GUARD_REWRITES = [
+  { guard: 'isFixedLengthArray', bounds: [0], replacement: 'isEmpty' },
+  { guard: 'isMaxLengthArray', bounds: [0], replacement: 'isEmpty' },
+  { guard: 'isBoundedLengthArray', bounds: [0, 0], replacement: 'isEmpty' },
+  { guard: 'isMinLengthArray', bounds: [1], replacement: 'isNonEmpty' },
+  { guard: 'isFixedLengthTuple', bounds: [0], replacement: 'isEmptyTuple' },
+  { guard: 'isMaxLengthTuple', bounds: [0], replacement: 'isEmptyTuple' },
+  {
+    guard: 'isBoundedLengthTuple',
+    bounds: [0, 0],
+    replacement: 'isEmptyTuple',
+  },
+  { guard: 'isMinLengthTuple', bounds: [1], replacement: 'isNonEmptyTuple' },
+] as const satisfies readonly Readonly<{
+  guard: string;
+  bounds: readonly number[];
+  replacement: string;
+}>[];
+
+export const preferCanonicalLengthGuard: TSESLint.RuleModule<
+  MessageIds,
+  Options
+> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Normalize array-length checks to their canonical `Arr` guard: `xs.length <op> n` becomes the matching `Arr.is*` guard, and a degenerate guard becomes the named one for its family (`Arr.isFixedLengthArray(0, xs)` → `Arr.isEmpty`, `Arr.isFixedLengthTuple(0, xs)` → `Arr.isEmptyTuple`).',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: MESSAGES,
+  },
+
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+
+    const arrLocalName = getImportedLocalName(
+      getTsDataForgeImport(sourceCode.ast),
+      'Arr',
+    );
+
+    const comparisonVisitors = COMPARISON_RULES.map((rule) =>
+      rule.create(context),
+    );
+
+    if (arrLocalName === undefined) return mergeVisitors(comparisonVisitors);
+
+    return mergeVisitors([
+      ...comparisonVisitors,
+      {
+        CallExpression: (node) => {
+          const guardName = getGuardName(node, arrLocalName);
+
+          if (guardName === undefined) return;
+
+          const rewrite = GUARD_REWRITES.find(
+            (entry) => entry.guard === guardName,
+          );
+
+          if (rewrite === undefined || !matchesBounds(node, rewrite.bounds)) {
+            return;
+          }
+
+          // The array is the last argument; the bounds precede it.
+          const array = node.arguments[rewrite.bounds.length];
+
+          if (array === undefined) return;
+
+          const arrayText = sourceCode.getText(array);
+
+          context.report({
+            node,
+            messageId: 'useCanonicalGuard',
+            data: {
+              arrName: arrLocalName,
+              guard: guardName,
+              boundsText: [...rewrite.bounds.map(String), '…'].join(', '),
+              replacement: rewrite.replacement,
+            },
+            fix: (fixer) =>
+              fixer.replaceText(
+                node,
+                `${arrLocalName}.${rewrite.replacement}(${arrayText})`,
+              ),
+          });
+        },
+      },
+    ]);
+  },
+  defaultOptions: [],
+} as const;
+
+/**
+ * Combines several rule listeners into one, calling every handler registered
+ * for a given selector in order.
+ */
+const mergeVisitors = (
+  // `RuleListener` holds mutable AST handler signatures, so it is not deeply
+  // readonly.
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  visitors: readonly TSESLint.RuleListener[],
+): TSESLint.RuleListener => {
+  const mut_merged: Record<string, ((node: never) => void)[]> = {};
+
+  for (const visitor of visitors) {
+    for (const [selector, handler] of Object.entries(visitor)) {
+      if (typeof handler !== 'function') continue;
+
+      const mut_handlers = mut_merged[selector] ?? [];
+
+      mut_handlers.push(handler);
+
+      mut_merged[selector] = mut_handlers;
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(mut_merged).map(([selector, handlers]) => [
+      selector,
+      (node: never) => {
+        for (const handler of handlers) {
+          handler(node);
+        }
+      },
+    ]),
+  );
+};
+
+/** The `Arr.<guard>` method name of `node`, or `undefined` for other calls. */
+const getGuardName = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.CallExpression,
+  arrLocalName: string,
+): string | undefined => {
+  const { callee } = node;
+
+  return callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.object.type === AST_NODE_TYPES.Identifier &&
+    callee.object.name === arrLocalName &&
+    callee.property.type === AST_NODE_TYPES.Identifier
+    ? callee.property.name
+    : undefined;
+};
+
+/**
+ * Whether the call is `guard(...bounds, array)` with every bound written as the
+ * exact numeric literal the rewrite requires.
+ *
+ * The arity check also excludes the curried form (`guard(...bounds)`): the
+ * degenerate guards take only the array, so there is nothing to rewrite it to.
+ */
+const matchesBounds = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.CallExpression,
+  bounds: readonly number[],
+): boolean => {
+  const args = node.arguments;
+
+  if (args.length !== bounds.length + 1 || node.typeArguments !== undefined) {
+    return false;
+  }
+
+  return args.every(
+    (arg, index) =>
+      arg.type !== AST_NODE_TYPES.SpreadElement &&
+      (index === bounds.length ||
+        (arg.type === AST_NODE_TYPES.Literal && arg.value === bounds[index])),
+  );
+};

package/src/rules/prefer-canonical-length-guard.test.mts

@@ -0,0 +1,307 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { preferCanonicalLengthGuard } from './prefer-canonical-length-guard.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+    },
+  },
+});
+
+// The folded-in comparison rules are type-aware, so they need a TypeScript
+// program; the guard-normalization half does not.
+const typedTester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      projectService: {
+        allowDefaultProject: ['*.ts*'],
+      },
+      tsconfigRootDir: `${import.meta.dirname}/../..`,
+    },
+  },
+});
+
+describe('prefer-canonical-length-guard (folded-in length comparisons)', () => {
+  typedTester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [
+      {
+        name: 'ignores non-array length comparisons',
+        code: dedent`
+          const str = 'hello';
+          const ok = str.length > 0;
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'xs.length > 0 becomes Arr.isNonEmpty(xs)',
+        code: dedent`
+          const xs = [1, 2, 3];
+          const ok = xs.length > 0;
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          const xs = [1, 2, 3];
+          const ok = Arr.isNonEmpty(xs);
+        `,
+        errors: [{ messageId: 'useIsNonEmpty' }],
+      },
+      {
+        name: 'xs.length >= 2 becomes Arr.isMinLengthArray(2, xs)',
+        code: dedent`
+          const xs = [1, 2, 3];
+          const ok = xs.length >= 2;
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          const xs = [1, 2, 3];
+          const ok = Arr.isMinLengthArray(2, xs);
+        `,
+        errors: [{ messageId: 'useIsMinLengthArray' }],
+      },
+      {
+        name: 'xs.length === 3 becomes Arr.isFixedLengthArray(3, xs)',
+        code: dedent`
+          const xs = [1, 2, 3];
+          const ok = xs.length === 3;
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          const xs = [1, 2, 3];
+          const ok = Arr.isFixedLengthArray(3, xs);
+        `,
+        errors: [{ messageId: 'useIsFixedLengthArray' }],
+      },
+    ],
+  });
+});
+
+describe('prefer-canonical-length-guard', () => {
+  tester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [
+      {
+        name: 'ignores non-degenerate bounds',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isFixedLengthTuple(2, xs);
+        `,
+      },
+      {
+        name: 'ignores isMinLengthArray with a bound other than 1',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isMinLengthArray(2, xs);
+        `,
+      },
+      {
+        name: 'ignores isBoundedLengthTuple unless both bounds are 0',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isBoundedLengthTuple(0, 1, xs);
+        `,
+      },
+      {
+        name: 'ignores a non-literal bound',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const n = 0;
+          const ok = Arr.isFixedLengthTuple(n, xs);
+        `,
+      },
+      {
+        name: 'ignores an Arr that is not from ts-data-forge',
+        code: dedent`
+          import { Arr } from './my-helpers.mjs';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isFixedLengthTuple(0, xs);
+        `,
+      },
+      {
+        name: 'ignores already-canonical guards',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isEmpty(xs);
+        `,
+      },
+      {
+        name: 'ignores spread arguments',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const args: readonly [readonly number[], 0];
+          const ok = Arr.isFixedLengthTuple(...args);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'isFixedLengthArray(0, xs) becomes isEmpty(xs)',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isFixedLengthArray(0, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isEmpty(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'isMinLengthTuple(1, xs) becomes isNonEmptyTuple(xs)',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isMinLengthTuple(1, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isNonEmptyTuple(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'isFixedLengthTuple(0, xs) becomes isEmptyTuple(xs)',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isFixedLengthTuple(0, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isEmptyTuple(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'isMaxLengthTuple(0, xs) becomes isEmptyTuple(xs)',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isMaxLengthTuple(0, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isEmptyTuple(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'isBoundedLengthTuple(0, 0, xs) becomes isEmptyTuple(xs)',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isBoundedLengthTuple(0, 0, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isEmptyTuple(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'isMinLengthArray(1, xs) becomes isNonEmpty(xs)',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isMinLengthArray(1, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isNonEmpty(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'keeps a complex array expression intact',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const obj: Readonly<{ items: readonly number[] }>;
+          const ok = Arr.isFixedLengthTuple(0, obj.items.filter((x) => x > 0));
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const obj: Readonly<{ items: readonly number[] }>;
+          const ok = Arr.isEmptyTuple(obj.items.filter((x) => x > 0));
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'resolves an aliased Arr import',
+        code: dedent`
+          import { Arr as A } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = A.isFixedLengthTuple(0, xs);
+        `,
+        output: dedent`
+          import { Arr as A } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = A.isEmptyTuple(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+      {
+        name: 'rewrites several guards in one file',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const a = Arr.isFixedLengthTuple(0, xs);
+          const b = Arr.isMinLengthArray(1, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const a = Arr.isEmptyTuple(xs);
+          const b = Arr.isNonEmpty(xs);
+        `,
+        errors: [
+          { messageId: 'useCanonicalGuard' },
+          { messageId: 'useCanonicalGuard' },
+        ],
+      },
+    ],
+  });
+});

package/src/rules/prefer-range-for-loop.mts

@@ -50,7 +50,7 @@ export const preferRangeForLoop: TSESLint.RuleModule<MessageIds, Options> = {
         if (
           node.init?.type !== AST_NODE_TYPES.VariableDeclaration ||
           node.init.kind !== 'let' ||
-          !Arr.isFixedLengthTuple(node.init.declarations, 1)
+          !Arr.isFixedLengthTuple(1, node.init.declarations)
         ) {
           return;
         }

package/src/rules/rules.mts

@@ -1,14 +1,11 @@
 import { type ESLintPlugin } from '../types.mjs';
 import { noUnnecessaryTypeGuard } from './no-unnecessary-type-guard.mjs';
 import { preferArrIsArray } from './prefer-arr-is-array.mjs';
-import { preferArrIsBoundedLengthArray } from './prefer-arr-is-bounded-length-array.mjs';
-import { preferArrIsFixedLengthArray } from './prefer-arr-is-fixed-length-array.mjs';
-import { preferArrIsMaxLengthArray } from './prefer-arr-is-max-length-array.mjs';
-import { preferArrIsMinLengthArray } from './prefer-arr-is-min-length-array.mjs';
-import { preferArrIsNonEmpty } from './prefer-arr-is-non-empty.mjs';
 import { preferArrSum } from './prefer-arr-sum.mjs';
 import { preferAsInt } from './prefer-as-int.mjs';
 import { preferCanonicalArraySlicing } from './prefer-canonical-array-slicing.mjs';
+import { preferCanonicalLengthCast } from './prefer-canonical-length-cast.mjs';
+import { preferCanonicalLengthGuard } from './prefer-canonical-length-guard.mjs';
 import { preferComparisonOverNullishGuard } from './prefer-comparison-over-nullish-guard.mjs';
 import { preferIsNonNullObject } from './prefer-is-non-null-object.mjs';
 import { preferIsRecordAndHasKey } from './prefer-is-record-and-has-key.mjs';
@@ -18,12 +15,9 @@ import { preferRangeForLoop } from './prefer-range-for-loop.mjs';
 
 export const tsDataForgeRules = {
   'prefer-canonical-array-slicing': preferCanonicalArraySlicing,
-  'prefer-arr-is-min-length-array': preferArrIsMinLengthArray,
-  'prefer-arr-is-max-length-array': preferArrIsMaxLengthArray,
-  'prefer-arr-is-bounded-length-array': preferArrIsBoundedLengthArray,
-  'prefer-arr-is-fixed-length-array': preferArrIsFixedLengthArray,
+  'prefer-canonical-length-guard': preferCanonicalLengthGuard,
+  'prefer-canonical-length-cast': preferCanonicalLengthCast,
   'prefer-arr-is-array': preferArrIsArray,
-  'prefer-arr-is-non-empty': preferArrIsNonEmpty,
   'prefer-arr-sum': preferArrSum,
   'prefer-as-int': preferAsInt,
   'prefer-is-non-null-object': preferIsNonNullObject,

package/src/types.mts

@@ -2,3 +2,5 @@ import { type TSESLint } from '@typescript-eslint/utils';
 import { type DeepReadonly } from 'ts-type-forge';
 
 export type ESLintPlugin = DeepReadonly<TSESLint.FlatConfig.Plugin>;
+
+export type ESLintFlatConfig = DeepReadonly<TSESLint.FlatConfig.Config>;