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

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

@@ -52,28 +52,44 @@ const MESSAGES = {
 } as const satisfies Record<MessageIds, string>;
 
 /**
- * Length guards whose bound makes them redundant with `Arr.isEmpty` /
- * `Arr.isNonEmpty`, keyed by guard name.
+ * Length guards whose bound makes them redundant with a named degenerate
+ * guard, keyed by guard name.
  *
- * `isEmpty` narrows to `FixedLengthArray<0, E> & Xs` and `isNonEmpty` to
- * `MinLengthArray<1, E> & Xs`, so:
+ * Every entry stays inside its own family rather than crossing the
+ * branded/structural divide:
  *
- * - The `*Array` entries are **type-identical** — `isFixedLengthArray(xs, 0)`
- *   and `isMinLengthArray(xs, 1)` produce exactly those types.
- * - The `*Tuple` entries **narrow**: they resolve to the structural
- *   `readonly []` / `readonly [E, ...E[]]`, and the canonical guards add the
- *   brand on top. The result stays assignable everywhere the old type was, so
- *   the rewrite is safe, but it is a strengthening rather than a pure rename.
+ * - 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: 'isFixedLengthTuple', bounds: [0], replacement: 'isEmpty' },
-  { guard: 'isMaxLengthTuple', bounds: [0], replacement: 'isEmpty' },
   { guard: 'isMaxLengthArray', bounds: [0], replacement: 'isEmpty' },
-  { guard: 'isBoundedLengthTuple', bounds: [0, 0], replacement: 'isEmpty' },
   { guard: 'isBoundedLengthArray', bounds: [0, 0], replacement: 'isEmpty' },
   { guard: 'isMinLengthArray', bounds: [1], replacement: 'isNonEmpty' },
-  { guard: 'isMinLengthTuple', 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[];
@@ -88,7 +104,7 @@ export const preferCanonicalLengthGuard: TSESLint.RuleModule<
     type: 'suggestion',
     docs: {
       description:
-        'Normalize array-length checks to their canonical `Arr` guard: `xs.length <op> n` becomes the matching `Arr.is*` guard, and degenerate guards (e.g. `Arr.isFixedLengthTuple(xs, 0)`) become `Arr.isEmpty` / `Arr.isNonEmpty`.',
+        '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: [],
@@ -125,7 +141,8 @@ export const preferCanonicalLengthGuard: TSESLint.RuleModule<
             return;
           }
 
-          const [array] = node.arguments;
+          // The array is the last argument; the bounds precede it.
+          const array = node.arguments[rewrite.bounds.length];
 
           if (array === undefined) return;
 
@@ -137,7 +154,7 @@ export const preferCanonicalLengthGuard: TSESLint.RuleModule<
             data: {
               arrName: arrLocalName,
               guard: guardName,
-              boundsText: ['…', ...rewrite.bounds.map(String)].join(', '),
+              boundsText: [...rewrite.bounds.map(String), '…'].join(', '),
               replacement: rewrite.replacement,
             },
             fix: (fixer) =>
@@ -207,8 +224,11 @@ const getGuardName = (
 };
 
 /**
- * Whether the call is `guard(array, ...bounds)` with every bound written as the
+ * 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
@@ -224,8 +244,7 @@ const matchesBounds = (
   return args.every(
     (arg, index) =>
       arg.type !== AST_NODE_TYPES.SpreadElement &&
-      (index === 0 ||
-        (arg.type === AST_NODE_TYPES.Literal &&
-          arg.value === bounds[index - 1])),
+      (index === bounds.length ||
+        (arg.type === AST_NODE_TYPES.Literal && arg.value === bounds[index])),
   );
 };

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

@@ -55,7 +55,7 @@ describe('prefer-canonical-length-guard (folded-in length comparisons)', () => {
         errors: [{ messageId: 'useIsNonEmpty' }],
       },
       {
-        name: 'xs.length >= 2 becomes Arr.isMinLengthArray(xs, 2)',
+        name: 'xs.length >= 2 becomes Arr.isMinLengthArray(2, xs)',
         code: dedent`
           const xs = [1, 2, 3];
           const ok = xs.length >= 2;
@@ -63,12 +63,12 @@ describe('prefer-canonical-length-guard (folded-in length comparisons)', () => {
         output: dedent`
           import { Arr } from 'ts-data-forge';
           const xs = [1, 2, 3];
-          const ok = Arr.isMinLengthArray(xs, 2);
+          const ok = Arr.isMinLengthArray(2, xs);
         `,
         errors: [{ messageId: 'useIsMinLengthArray' }],
       },
       {
-        name: 'xs.length === 3 becomes Arr.isFixedLengthArray(xs, 3)',
+        name: 'xs.length === 3 becomes Arr.isFixedLengthArray(3, xs)',
         code: dedent`
           const xs = [1, 2, 3];
           const ok = xs.length === 3;
@@ -76,7 +76,7 @@ describe('prefer-canonical-length-guard (folded-in length comparisons)', () => {
         output: dedent`
           import { Arr } from 'ts-data-forge';
           const xs = [1, 2, 3];
-          const ok = Arr.isFixedLengthArray(xs, 3);
+          const ok = Arr.isFixedLengthArray(3, xs);
         `,
         errors: [{ messageId: 'useIsFixedLengthArray' }],
       },
@@ -93,7 +93,7 @@ describe('prefer-canonical-length-guard', () => {
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isFixedLengthTuple(xs, 2);
+          const ok = Arr.isFixedLengthTuple(2, xs);
         `,
       },
       {
@@ -102,7 +102,7 @@ describe('prefer-canonical-length-guard', () => {
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isMinLengthArray(xs, 2);
+          const ok = Arr.isMinLengthArray(2, xs);
         `,
       },
       {
@@ -111,7 +111,7 @@ describe('prefer-canonical-length-guard', () => {
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isBoundedLengthTuple(xs, 0, 1);
+          const ok = Arr.isBoundedLengthTuple(0, 1, xs);
         `,
       },
       {
@@ -121,7 +121,7 @@ describe('prefer-canonical-length-guard', () => {
 
           declare const xs: readonly number[];
           const n = 0;
-          const ok = Arr.isFixedLengthTuple(xs, n);
+          const ok = Arr.isFixedLengthTuple(n, xs);
         `,
       },
       {
@@ -130,7 +130,7 @@ describe('prefer-canonical-length-guard', () => {
           import { Arr } from './my-helpers.mjs';
 
           declare const xs: readonly number[];
-          const ok = Arr.isFixedLengthTuple(xs, 0);
+          const ok = Arr.isFixedLengthTuple(0, xs);
         `,
       },
       {
@@ -154,12 +154,12 @@ describe('prefer-canonical-length-guard', () => {
     ],
     invalid: [
       {
-        name: 'isFixedLengthArray(xs, 0) becomes isEmpty(xs)',
+        name: 'isFixedLengthArray(0, xs) becomes isEmpty(xs)',
         code: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isFixedLengthArray(xs, 0);
+          const ok = Arr.isFixedLengthArray(0, xs);
         `,
         output: dedent`
           import { Arr } from 'ts-data-forge';
@@ -170,76 +170,76 @@ describe('prefer-canonical-length-guard', () => {
         errors: [{ messageId: 'useCanonicalGuard' }],
       },
       {
-        name: 'isMinLengthTuple(xs, 1) becomes isNonEmpty(xs)',
+        name: 'isMinLengthTuple(1, xs) becomes isNonEmptyTuple(xs)',
         code: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isMinLengthTuple(xs, 1);
+          const ok = Arr.isMinLengthTuple(1, xs);
         `,
         output: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isNonEmpty(xs);
+          const ok = Arr.isNonEmptyTuple(xs);
         `,
         errors: [{ messageId: 'useCanonicalGuard' }],
       },
       {
-        name: 'isFixedLengthTuple(xs, 0) becomes isEmpty(xs)',
+        name: 'isFixedLengthTuple(0, xs) becomes isEmptyTuple(xs)',
         code: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isFixedLengthTuple(xs, 0);
+          const ok = Arr.isFixedLengthTuple(0, xs);
         `,
         output: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isEmpty(xs);
+          const ok = Arr.isEmptyTuple(xs);
         `,
         errors: [{ messageId: 'useCanonicalGuard' }],
       },
       {
-        name: 'isMaxLengthTuple(xs, 0) becomes isEmpty(xs)',
+        name: 'isMaxLengthTuple(0, xs) becomes isEmptyTuple(xs)',
         code: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isMaxLengthTuple(xs, 0);
+          const ok = Arr.isMaxLengthTuple(0, xs);
         `,
         output: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isEmpty(xs);
+          const ok = Arr.isEmptyTuple(xs);
         `,
         errors: [{ messageId: 'useCanonicalGuard' }],
       },
       {
-        name: 'isBoundedLengthTuple(xs, 0, 0) becomes isEmpty(xs)',
+        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(xs, 0, 0);
+          const ok = Arr.isBoundedLengthTuple(0, 0, xs);
         `,
         output: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isEmpty(xs);
+          const ok = Arr.isEmptyTuple(xs);
         `,
         errors: [{ messageId: 'useCanonicalGuard' }],
       },
       {
-        name: 'isMinLengthArray(xs, 1) becomes isNonEmpty(xs)',
+        name: 'isMinLengthArray(1, xs) becomes isNonEmpty(xs)',
         code: dedent`
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = Arr.isMinLengthArray(xs, 1);
+          const ok = Arr.isMinLengthArray(1, xs);
         `,
         output: dedent`
           import { Arr } from 'ts-data-forge';
@@ -255,13 +255,13 @@ describe('prefer-canonical-length-guard', () => {
           import { Arr } from 'ts-data-forge';
 
           declare const obj: Readonly<{ items: readonly number[] }>;
-          const ok = Arr.isFixedLengthTuple(obj.items.filter((x) => x > 0), 0);
+          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.isEmpty(obj.items.filter((x) => x > 0));
+          const ok = Arr.isEmptyTuple(obj.items.filter((x) => x > 0));
         `,
         errors: [{ messageId: 'useCanonicalGuard' }],
       },
@@ -271,13 +271,13 @@ describe('prefer-canonical-length-guard', () => {
           import { Arr as A } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = A.isFixedLengthTuple(xs, 0);
+          const ok = A.isFixedLengthTuple(0, xs);
         `,
         output: dedent`
           import { Arr as A } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const ok = A.isEmpty(xs);
+          const ok = A.isEmptyTuple(xs);
         `,
         errors: [{ messageId: 'useCanonicalGuard' }],
       },
@@ -287,14 +287,14 @@ describe('prefer-canonical-length-guard', () => {
           import { Arr } from 'ts-data-forge';
 
           declare const xs: readonly number[];
-          const a = Arr.isFixedLengthTuple(xs, 0);
-          const b = Arr.isMinLengthArray(xs, 1);
+          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.isEmpty(xs);
+          const a = Arr.isEmptyTuple(xs);
           const b = Arr.isNonEmpty(xs);
         `,
         errors: [

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

@@ -4,6 +4,7 @@ import { preferArrIsArray } from './prefer-arr-is-array.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';
@@ -15,6 +16,7 @@ import { preferRangeForLoop } from './prefer-range-for-loop.mjs';
 export const tsDataForgeRules = {
   'prefer-canonical-array-slicing': preferCanonicalArraySlicing,
   'prefer-canonical-length-guard': preferCanonicalLengthGuard,
+  'prefer-canonical-length-cast': preferCanonicalLengthCast,
   'prefer-arr-is-array': preferArrIsArray,
   'prefer-arr-sum': preferArrSum,
   'prefer-as-int': preferAsInt,