eslint-plugin-ts-data-forge 0.1.0

package/src/rules/ast-utils.mts

@@ -0,0 +1,169 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { type DeepReadonly } from 'ts-type-forge';
+
+const isIntegerLiteral = (node: DeepReadonly<TSESTree.Expression>): boolean =>
+  node.type === AST_NODE_TYPES.Literal &&
+  typeof node.value === 'number' &&
+  Number.isInteger(node.value);
+
+export const isIntegerLiteralOrConstant = (
+  node: DeepReadonly<TSESTree.Expression>,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+): boolean => {
+  // Direct integer literal (e.g., 3)
+  if (isIntegerLiteral(node)) return true;
+
+  // Identifier referencing a const variable initialized with an integer literal
+  if (node.type !== AST_NODE_TYPES.Identifier) return false;
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  const scope = sourceCode.getScope(node as TSESTree.Node);
+
+  const variable = findVariable(scope, node.name);
+
+  if (variable === undefined) return false;
+
+  // Must have exactly one definition (const)
+  if (variable.defs.length !== 1) return false;
+
+  const def = variable.defs[0];
+
+  if (def === undefined) return false;
+
+  if (!isVariableDefinition(def)) return false;
+
+  if (def.parent.kind !== 'const') return false;
+
+  if (def.node.init == null) return false;
+
+  // Reject if there is an explicit type annotation (e.g., `const n: number = 3`)
+  // because the literal type is widened and type guard cannot narrow it.
+  if (def.node.id.typeAnnotation !== undefined) return false;
+
+  return isIntegerLiteral(def.node.init);
+};
+
+export const isLengthAccess = (
+  node: DeepReadonly<TSESTree.Expression>,
+): node is TSESTree.MemberExpression =>
+  node.type === AST_NODE_TYPES.MemberExpression &&
+  node.property.type === AST_NODE_TYPES.Identifier &&
+  node.property.name === 'length';
+
+type LengthComparison = Readonly<{
+  array: TSESTree.Expression;
+  bound: TSESTree.Expression;
+  kind: 'max' | 'min';
+}>;
+
+/**
+ * Parses a `<array>.length <op> <bound>` comparison (in either operand order)
+ * into its array expression, integer-literal/`const` `bound`, and whether it is
+ * a lower (`min`) or upper (`max`) length bound. Returns `undefined` for
+ * anything else.
+ *
+ * - `xs.length >= n` / `n <= xs.length` → `min`
+ * - `xs.length <= n` / `n >= xs.length` → `max`
+ */
+export const parseLengthComparison = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Expression,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+): LengthComparison | undefined => {
+  if (
+    node.type !== AST_NODE_TYPES.BinaryExpression ||
+    (node.operator !== '>=' && node.operator !== '<=')
+  ) {
+    return undefined;
+  }
+
+  const { left, right, operator } = node;
+
+  const lengthOnLeft = isLengthAccess(left);
+
+  const lengthSide = lengthOnLeft ? left : right;
+
+  const boundSide = lengthOnLeft ? right : left;
+
+  if (!isLengthAccess(lengthSide)) return undefined;
+
+  if (!isIntegerLiteralOrConstant(boundSide, sourceCode)) return undefined;
+
+  const kind: LengthComparison['kind'] = (
+    lengthOnLeft ? operator === '>=' : operator === '<='
+  )
+    ? 'min'
+    : 'max';
+
+  return { array: lengthSide.object, bound: boundSide, kind };
+};
+
+/**
+ * `true` when `node` is one operand of an `a && b` whose other operand is the
+ * complementary length bound (`min` vs `max`) on the same array — i.e. the two
+ * together form the `Arr.isBoundedLengthArray` pattern handled by
+ * `prefer-arr-is-bounded-length-array`. The single-bound rules skip such
+ * operands so the bounded rule rewrites the whole `&&` instead of the parts.
+ */
+export const isPartOfBoundedLengthCheck = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.BinaryExpression,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+): boolean => {
+  const { parent } = node;
+
+  if (
+    parent.type !== AST_NODE_TYPES.LogicalExpression ||
+    parent.operator !== '&&'
+  ) {
+    return false;
+  }
+
+  const self = parseLengthComparison(node, sourceCode);
+
+  if (self === undefined) return false;
+
+  const sibling = parent.left === node ? parent.right : parent.left;
+
+  const other = parseLengthComparison(sibling, sourceCode);
+
+  if (other === undefined) return false;
+
+  return (
+    self.kind !== other.kind &&
+    sourceCode.getText(self.array) === sourceCode.getText(other.array)
+  );
+};
+
+type VariableDefinition = Readonly<{
+  type: string;
+  parent: TSESTree.VariableDeclaration;
+  node: TSESTree.VariableDeclarator;
+}>;
+
+const isVariableDefinition = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  def: TSESLint.Scope.Definition,
+): def is TSESLint.Scope.Definition & VariableDefinition =>
+  (def.type as string) === 'Variable';
+
+const findVariable = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  scope: TSESLint.Scope.Scope,
+  name: string,
+): TSESLint.Scope.Variable | undefined => {
+  const variable = scope.set.get(name);
+
+  if (variable !== undefined) return variable;
+
+  if (scope.upper === null) return undefined;
+
+  return findVariable(scope.upper, name);
+};

package/src/rules/branded-number-types.mts

@@ -0,0 +1,47 @@
+// Keep this list in sync with the `as<Type>` cast functions exported by
+// ts-data-forge. `pnpm run check:branded-number-types` (also run during the
+// build) fails if a branded number type is missing here or no longer exists.
+const brandedNumberTypes = [
+  'FiniteNumber',
+  'Int',
+  'Int16',
+  'Int32',
+  'Int8',
+  'NegativeFiniteNumber',
+  'NegativeInt',
+  'NegativeSafeInt',
+  'NonNegativeFiniteNumber',
+  'NonNegativeInt16',
+  'NonNegativeInt32',
+  'NonPositiveFiniteNumber',
+  'NonPositiveInt',
+  'NonPositiveSafeInt',
+  'NonZeroFiniteNumber',
+  'NonZeroInt',
+  'NonZeroInt16',
+  'NonZeroInt32',
+  'NonZeroSafeInt',
+  'NonZeroUint16',
+  'NonZeroUint32',
+  'PositiveFiniteNumber',
+  'PositiveInt',
+  'PositiveInt16',
+  'PositiveInt32',
+  'PositiveSafeInt',
+  'PositiveUint16',
+  'PositiveUint32',
+  'SafeInt',
+  'SafeUint',
+  'Uint',
+  'Uint16',
+  'Uint32',
+  'Uint8',
+] as const;
+
+/**
+ * Branded number types from ts-data-forge and their corresponding as* functions
+ */
+export const brandedNumberTypeNameToFunctionName: ReadonlyMap<
+  string,
+  `as${string}`
+> = new Map(brandedNumberTypes.map((t) => [t, `as${t}`]));

package/src/rules/constants.mts

@@ -0,0 +1 @@
+export const TS_DATA_FORGE_MODULE = 'ts-data-forge';

package/src/rules/import-utils.mts

@@ -0,0 +1,152 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { type DeepReadonly } from 'ts-type-forge';
+import { TS_DATA_FORGE_MODULE } from './constants.mjs';
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+export const getTsDataForgeImport = (
+  program: TSESTree.Program,
+): TSESTree.ImportDeclaration | undefined =>
+  program.body.find(
+    (node): node is TSESTree.ImportDeclaration =>
+      node.type === AST_NODE_TYPES.ImportDeclaration &&
+      node.source.value === TS_DATA_FORGE_MODULE,
+  );
+
+export const getNamedImports = (
+  node: DeepReadonly<TSESTree.ImportDeclaration> | undefined,
+): readonly string[] => {
+  if (node === undefined) return [];
+
+  return node.specifiers.flatMap((specifier) =>
+    specifier.type === AST_NODE_TYPES.ImportSpecifier
+      ? (() => {
+          const importedName =
+            specifier.imported.type === AST_NODE_TYPES.Identifier
+              ? specifier.imported.name
+              : specifier.imported.value;
+
+          return typeof importedName === 'string' ? [importedName] : [];
+        })()
+      : [],
+  );
+};
+
+/**
+ * Returns the in-scope local name a given canonical export is imported as
+ * (handling aliases such as `import { isX as y }` → `'y'`), or `undefined` when
+ * it is not imported. Used so autofixes reference the binding that actually
+ * exists rather than the canonical name.
+ */
+export const getImportedLocalName = (
+  node: DeepReadonly<TSESTree.ImportDeclaration> | undefined,
+  importedName: string,
+): string | undefined =>
+  node?.specifiers.find(
+    (specifier) =>
+      specifier.type === AST_NODE_TYPES.ImportSpecifier &&
+      (specifier.imported.type === AST_NODE_TYPES.Identifier
+        ? specifier.imported.name
+        : specifier.imported.value) === importedName,
+  )?.local.name;
+
+type ResolvedCallee = Readonly<{
+  /** The canonical (imported) ts-data-forge name, regardless of local alias. */
+  canonicalName: string;
+  /** The identifier node to rewrite when replacing the callee name. */
+  propertyNode: TSESTree.Node;
+  /** Whether the call was made through a namespace import (`tf.isX(...)`). */
+  isNamespace: boolean;
+}>;
+
+/**
+ * Builds a resolver that maps a call expression's callee to the canonical
+ * ts-data-forge function it refers to. Handles named imports (including aliases
+ * such as `import { isX as y }`) and namespace imports (`import * as tf` →
+ * `tf.isX(...)`). Returns `undefined` for any callee that does not reference the
+ * given ts-data-forge import.
+ */
+export const buildCalleeResolver = (
+  importDecl: TSESTree.ImportDeclaration | undefined,
+): ((
+  callee: DeepReadonly<TSESTree.Expression>,
+) => ResolvedCallee | undefined) => {
+  const specifiers = importDecl?.specifiers ?? [];
+
+  const namespaceName = specifiers.find(
+    (specifier) => specifier.type === AST_NODE_TYPES.ImportNamespaceSpecifier,
+  )?.local.name;
+
+  const localToCanonical = new Map<string, string>(
+    specifiers.flatMap((specifier) => {
+      if (specifier.type !== AST_NODE_TYPES.ImportSpecifier) return [];
+
+      const importedName =
+        specifier.imported.type === AST_NODE_TYPES.Identifier
+          ? specifier.imported.name
+          : specifier.imported.value;
+
+      return typeof importedName === 'string'
+        ? [[specifier.local.name, importedName] as const]
+        : [];
+    }),
+  );
+
+  return (callee) => {
+    if (callee.type === AST_NODE_TYPES.Identifier) {
+      const canonicalName = localToCanonical.get(callee.name);
+
+      return canonicalName === undefined
+        ? undefined
+        : {
+            canonicalName,
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            propertyNode: callee as TSESTree.Node,
+            isNamespace: false,
+          };
+    }
+
+    if (
+      callee.type === AST_NODE_TYPES.MemberExpression &&
+      !callee.computed &&
+      callee.object.type === AST_NODE_TYPES.Identifier &&
+      namespaceName !== undefined &&
+      callee.object.name === namespaceName &&
+      callee.property.type === AST_NODE_TYPES.Identifier
+    ) {
+      return {
+        canonicalName: callee.property.name,
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        propertyNode: callee.property as TSESTree.Node,
+        isNamespace: true,
+      };
+    }
+
+    return undefined;
+  };
+};
+
+export const buildImportFixes = (
+  fixer: TSESLint.RuleFixer,
+  program: TSESTree.Program,
+  _tsDataForgeImport: TSESTree.ImportDeclaration | undefined,
+  requiredNames: readonly string[],
+): readonly TSESLint.RuleFix[] => {
+  const specifierText = requiredNames.join(', ');
+
+  const importStatement =
+    `import { ${specifierText} } from '${TS_DATA_FORGE_MODULE}';` as const;
+
+  const newLine = '\n';
+
+  const insertionText = `${importStatement}${newLine}` as const;
+
+  // Always insert at the beginning of the file
+  // (organize-imports will handle merging/deduplication)
+  return [fixer.insertTextBefore(program, insertionText)];
+};
+/* eslint-enable @typescript-eslint/prefer-readonly-parameter-types */

package/src/rules/index.mts

@@ -0,0 +1 @@
+export * from './rules.mjs';