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

package/src/plugin.mts

@@ -1,9 +1,52 @@
 import { tsDataForgeRules } from './rules/index.mjs';
-import { type ESLintPlugin } from './types.mjs';
+import { type ESLintFlatConfig, type ESLintPlugin } from './types.mjs';
 
-export const eslintPluginTsDataForge: ESLintPlugin = {
+/**
+ * Every rule this plugin ships, at `error`.
+ *
+ * The `satisfies` clause below is keyed off {@link tsDataForgeRules}, so adding
+ * a rule without listing it here fails to type-check.
+ */
+const recommendedRules = {
+  'ts-data-forge/prefer-canonical-array-slicing': 'error',
+  'ts-data-forge/prefer-canonical-length-guard': 'error',
+  'ts-data-forge/prefer-arr-is-array': 'error',
+  'ts-data-forge/prefer-arr-sum': 'error',
+  'ts-data-forge/prefer-as-int': 'error',
+  'ts-data-forge/prefer-is-non-null-object': 'error',
+  'ts-data-forge/prefer-range-for-loop': 'error',
+  'ts-data-forge/prefer-is-record-and-has-key': 'error',
+  'ts-data-forge/prefer-num-safe-parse-int': 'error',
+  'ts-data-forge/prefer-num-safe-parse-float': 'error',
+  'ts-data-forge/no-unnecessary-type-guard': 'error',
+  'ts-data-forge/prefer-comparison-over-nullish-guard': 'error',
+} as const satisfies Readonly<
+  Record<`ts-data-forge/${keyof typeof tsDataForgeRules}`, 'error'>
+>;
+
+const recommendedConfig = {
+  name: 'ts-data-forge/recommended',
+  plugins: {
+    // Resolved lazily so that this config registers the *same* object that
+    // `eslintPluginTsDataForge` refers to. ESLint rejects a plugin name that
+    // maps to two different objects with `Cannot redefine plugin`, which is
+    // what a user combining this preset with their own
+    // `plugins: { 'ts-data-forge': eslintPluginTsDataForge }` entry would hit
+    // if the preset embedded a separate copy of the plugin.
+    get 'ts-data-forge'(): ESLintPlugin {
+      return eslintPluginTsDataForge;
+    },
+  },
+  rules: recommendedRules,
+} as const satisfies ESLintFlatConfig;
+
+export const eslintPluginTsDataForge = {
   meta: {
     name: 'eslint-plugin-ts-data-forge',
   },
   rules: tsDataForgeRules,
-} as const;
+  configs: {
+    /** Enables every rule of this plugin at `error`. */
+    recommended: recommendedConfig,
+  },
+} as const satisfies ESLintPlugin;

package/src/plugin.test.mts

@@ -0,0 +1,24 @@
+import { eslintPluginTsDataForge } from './plugin.mjs';
+import { tsDataForgeRules } from './rules/index.mjs';
+
+describe('eslintPluginTsDataForge.configs.recommended', () => {
+  const recommended = eslintPluginTsDataForge.configs.recommended;
+
+  test('enables every rule of the plugin, and nothing else, at "error"', () => {
+    assert.deepStrictEqual(
+      recommended.rules,
+      Object.fromEntries(
+        Object.keys(tsDataForgeRules).map((name) => [
+          `ts-data-forge/${name}`,
+          'error',
+        ]),
+      ),
+    );
+  });
+
+  test('registers the exported plugin object itself', () => {
+    // Registering a *copy* would make `Cannot redefine plugin` errors possible
+    // for users who also list the plugin in their own `plugins` record.
+    expect(recommended.plugins['ts-data-forge']).toBe(eslintPluginTsDataForge);
+  });
+});

package/src/rule-types.mts

@@ -43,7 +43,7 @@ namespace PreferCanonicalArraySlicing {
 }
 
 /**
- * @description Replace `xs.length >= n` with `Arr.isMinLengthArray(xs, n)` from ts-data-forge.
+ * @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`.
  *
  *  ```md
  *  | key        | value      |
@@ -53,52 +53,7 @@ namespace PreferCanonicalArraySlicing {
  *  | fixable    | code       |
  *  ```
  */
-namespace PreferArrIsMinLengthArray {
-  export type RuleEntry = Linter.StringSeverity;
-}
-
-/**
- * @description Replace `xs.length <= n` with `Arr.isMaxLengthArray(xs, n)` from ts-data-forge.
- *
- *  ```md
- *  | key        | value      |
- *  | :--------- | :--------- |
- *  | type       | suggestion |
- *  | deprecated | false      |
- *  | fixable    | code       |
- *  ```
- */
-namespace PreferArrIsMaxLengthArray {
-  export type RuleEntry = Linter.StringSeverity;
-}
-
-/**
- * @description Replace `xs.length >= min && xs.length <= max` with `Arr.isBoundedLengthArray(xs, min, max)` from ts-data-forge.
- *
- *  ```md
- *  | key        | value      |
- *  | :--------- | :--------- |
- *  | type       | suggestion |
- *  | deprecated | false      |
- *  | fixable    | code       |
- *  ```
- */
-namespace PreferArrIsBoundedLengthArray {
-  export type RuleEntry = Linter.StringSeverity;
-}
-
-/**
- * @description Replace `xs.length === n` with `Arr.isFixedLengthArray(xs, n)` from ts-data-forge.
- *
- *  ```md
- *  | key        | value      |
- *  | :--------- | :--------- |
- *  | type       | suggestion |
- *  | deprecated | false      |
- *  | fixable    | code       |
- *  ```
- */
-namespace PreferArrIsFixedLengthArray {
+namespace PreferCanonicalLengthGuard {
   export type RuleEntry = Linter.StringSeverity;
 }
 
@@ -117,21 +72,6 @@ namespace PreferArrIsArray {
   export type RuleEntry = Linter.StringSeverity;
 }
 
-/**
- * @description Replace `xs.length > 0` with `Arr.isNonEmpty(xs)` from ts-data-forge.
- *
- *  ```md
- *  | key        | value      |
- *  | :--------- | :--------- |
- *  | type       | suggestion |
- *  | deprecated | false      |
- *  | fixable    | code       |
- *  ```
- */
-namespace PreferArrIsNonEmpty {
-  export type RuleEntry = Linter.StringSeverity;
-}
-
 /**
  * @description Replace `xs.reduce((a, b) => a + b, 0)` with `Arr.sum(xs)` or `Arr.sumBy(xs, fn)` from ts-data-forge.
  *
@@ -297,12 +237,8 @@ namespace PreferComparisonOverNullishGuard {
 
 export type EslintTsDataForgeRules = Readonly<{
   'ts-data-forge/prefer-canonical-array-slicing': PreferCanonicalArraySlicing.RuleEntry;
-  'ts-data-forge/prefer-arr-is-min-length-array': PreferArrIsMinLengthArray.RuleEntry;
-  'ts-data-forge/prefer-arr-is-max-length-array': PreferArrIsMaxLengthArray.RuleEntry;
-  'ts-data-forge/prefer-arr-is-bounded-length-array': PreferArrIsBoundedLengthArray.RuleEntry;
-  'ts-data-forge/prefer-arr-is-fixed-length-array': PreferArrIsFixedLengthArray.RuleEntry;
+  'ts-data-forge/prefer-canonical-length-guard': PreferCanonicalLengthGuard.RuleEntry;
   'ts-data-forge/prefer-arr-is-array': PreferArrIsArray.RuleEntry;
-  'ts-data-forge/prefer-arr-is-non-empty': PreferArrIsNonEmpty.RuleEntry;
   'ts-data-forge/prefer-arr-sum': PreferArrSum.RuleEntry;
   'ts-data-forge/prefer-as-int': PreferAsInt.RuleEntry;
   'ts-data-forge/prefer-is-non-null-object': PreferIsNonNullObject.RuleEntry;

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

@@ -0,0 +1,231 @@
+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 `Arr.isEmpty` /
+ * `Arr.isNonEmpty`, keyed by guard name.
+ *
+ * `isEmpty` narrows to `FixedLengthArray<0, E> & Xs` and `isNonEmpty` to
+ * `MinLengthArray<1, E> & Xs`, so:
+ *
+ * - 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.
+ */
+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' },
+] 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 degenerate guards (e.g. `Arr.isFixedLengthTuple(xs, 0)`) become `Arr.isEmpty` / `Arr.isNonEmpty`.',
+    },
+    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;
+          }
+
+          const [array] = node.arguments;
+
+          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(array, ...bounds)` with every bound written as the
+ * exact numeric literal the rewrite requires.
+ */
+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 === 0 ||
+        (arg.type === AST_NODE_TYPES.Literal &&
+          arg.value === bounds[index - 1])),
+  );
+};