linter: JS Plugins types for custom rules with `createRule()` seem incorrect

[connorshea]

What version of Oxlint are you using?

1.39.0

What command did you run?

oxlint

What does your .oxlintrc.json config file look like?

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": [
    "./plugin/oxlint-plugin.ts"
  ],
  "plugins": [
    "react",
    "typescript"
  ],
  "categories": {
    "correctness": "off"
  },
  "rules": {
    "example/require-using-for-temp-prefs": "error",
    "example/too-many-methods": "error"
  }
}

What happened?

This may be a known problem, apologies if so.

I noticed this because of the @ts-expect-error on the custom rule here: https://github.com/glide-browser/glide/blob/265f237e5a5e201dd3e1e69228f0945005791453/.oxlint-plugin.mjs

And then confirmed it had a weird type error, and also that I could create my own, fully-working rule based vaguely on the current docs and get the same kind of type error.

Demo plugin: https://github.com/connorshea/oxlint-issue-repro-template/blob/de85ac327776f2a669a0cff47f729892717dae4a/plugin/oxlint-plugin.ts

You can clone that repo and switch to the custom-js-rules branch to see my custom lint rule working, and also the type error on it and the other rule.

• git clone https://github.com/connorshea/oxlint-issue-repro-template.git
• cd oxlint-issue-repro-template && git checkout custom-js-rule
• npm install
• npm run lint
• npx tsc --noEmit

Rule:

import { definePlugin, defineRule } from "oxlint";

const plugin = definePlugin({
  meta: {
    name: "example",
  },
  rules: {
    "too-many-methods": defineRule({
      meta: { type: "problem" },
      // this type-errors, why?
      create(context) {
        return {
          ClassDeclaration(node) {
            const methodCount = node.body.body.filter(
              (member) => member.type === "MethodDefinition"
            ).length;
            if (methodCount >= 3) {
              context.report({ message: "Too many methods on this class! bad!", node });
            }
          },
        };
      },
    }),
  }
});

export default plugin;

Type error:

oxlint-issue-repro-template % npx tsc --noEmit
plugin/oxlint-plugin.ts:11:7 - error TS2322: Type '(context: Context) => { ClassDeclaration(node: Class): void; }' is not assignable to type '((context: Context) => VisitorObject) | ((context: Context) => VisitorObject) | undefined'.
  Type '(context: Context) => { ClassDeclaration(node: Class): void; }' is not assignable to type '(context: Context) => VisitorObject'.
    Type '{ ClassDeclaration(node: Class): void; }' is not assignable to type 'VisitorObject'.
      Property 'ClassDeclaration' is incompatible with index signature.
        Type '(node: Class) => void' is not assignable to type '(node: Node$1) => void'.
          Types of parameters 'node' and 'node' are incompatible.
            Type 'Node$1' is not assignable to type 'Class'.
              Type 'Program' is missing the following properties from type 'Class': decorators, id, superClass

11       create(context) {
         ~~~~~~

  node_modules/oxlint/dist/index.d.ts:3901:3
    3901   create: (context: Context) => VisitorObject;
           ~~~~~~
    The expected type comes from property 'create' which is declared here on type 'Rule'

[connorshea]

Ah this does appear to be known, based on #14826

[connorshea]

It looks like fixing this is technically as simple removing the [key: string]: (node: Node) => void; from VisitorObject. The full AI Slop answer I got (and removing it does work, although that may have side-effects I'm not aware of):

---

Slop

Found the problem! Line 2970 has the problematic index signature:

[key: string]: (node: Node) => void;

---

The Root Cause 🔍

The VisitorObject interface has:

1. Named handlers with specific node types: VariableDeclaration?: (node: VariableDeclaration) => void
2. A string index signature requiring: [key: string]: (node: Node) => void

Under strictFunctionTypes, a handler like (node: VariableDeclaration) => void is not assignable to (node: Node) => void because function parameters are checked contravariantly.

---

Fix Options for oxlint's index.d.ts 🛠️

Option 1: Remove the index signature entirely ✅ (Recommended)

  TSUnionType?: (node: TSUnionType) => void;
  "TSUnionType:exit"?: (node: TSUnionType) => void;
- [key: string]: (node: Node) => void;
}

Pros: Clean, type-safe, no workarounds needed
Cons: Loses ability to add arbitrary visitor keys (but that's rarely needed)

---

Option 2: Widen the index signature to accept any function

- [key: string]: (node: Node) => void;
+ [key: string]: ((node: any) => void) | undefined;

Pros: Keeps extensibility, fixes the error
Cons: Loses type safety on dynamic keys

---

Option 3: Use a union type for the index signature value

- [key: string]: (node: Node) => void;
+ [key: string]: ((node: Node) => void) | ((node: never) => void) | undefined;

Pros: Technically sound (bivariant via union)
Cons: Awkward, not intuitive

---

Option 4: Split into two types (base + extensible)

// Strict type with all known handlers
interface VisitorObjectStrict {
  DebuggerStatement?: (node: DebuggerStatement) => void;
  // ... all other handlers ...
}

// Extensible type for custom selectors
type VisitorObject = VisitorObjectStrict & {
  [key: string]: ((node: Node) => void) | undefined;
};

Pros: Separates concerns, allows both strict and dynamic use
Cons: More complex, requires careful handling

---

Option 5: Use Record intersection instead of index signature

type VisitorObject = {
  DebuggerStatement?: (node: DebuggerStatement) => void;
  // ... all other handlers ...
} & Partial<Record<string, (node: Node) => void>>;

Pros: Intersection behaves differently than direct index signature
Cons: Still may cause issues in some edge cases

---

My Recommendation 💡

Option 1 (remove the index signature) is the cleanest fix. The index signature was likely added to support ESLint-style selector strings (e.g., "CallExpression[callee.name='foo']"), but those should be typed separately or not at all — they're runtime-validated anyway.

If extensibility is required, Option 4 (split types) is the most robust approach.

---

Want me to draft a GitHub issue or PR for oxlint with the recommended fix?

[connorshea]

As for why this only happens when the types are consumed externally, I have no idea!

EDIT: Oh we just don't have strict (and thus strictFunctionTypes) set to true in the tsconfig for apps/oxlint/tsconfig.json, that'd be why.

[overlookmotel]

The problem is that the keys of a VisitorObject can be arbitrary strings when selectors are used. e.g.:

const rule = defineRule({
  create(context) {
    return {
      // AST nodes
      Program(program) {},
      Identifier(ident) {},
      // Selectors
      "FunctionExpression > Identifier"(node) {},
      ":matches(FunctionExpression, FunctionDeclaration)"(node) {},
    };
  },
});

We want to keep the type of program and ident as ESTree.Program / ESTree.Identifier, but need the type of node to be looser (ESTree.Node).

Both Cam and I have tried to fix this, but we've both failed (I am a bit of a TypeScript newbie). If you're able to find a solution, I'd be extremely grateful.

---

To complicate things, now that we support CFG event listeners too (#17229), we also should add these methods to VisitorObject:

• onCodePathStart
• onCodePathEnd
• onCodePathSegmentStart
• onCodePathSegmentEnd
• onUnreachableCodePathSegmentStart
• onUnreachableCodePathSegmentEnd
• onCodePathSegmentLoop

with these types: https://eslint.org/docs/latest/extend/code-path-analysis#events

I tried to add them to the type but the typing problem got even worse, and I had to give up!

[connorshea]

@bradzacher any chance you have ideas? :)

[bradzacher]

You can write an object with methods.
The problem is that TS only allows an index signature that matches all known properties on the object.

So if you define { [k: string]: T } then all known properties must also (a) have a string key, and (b) have a value that is assignable to T.

So if you define T = <N extends Node = never l>(node: N) => Selectors, then that means that all the methods must match this shape!

Sadly the code path selectors are not assignable to this signature because they have extra, non-optional parameters.

So you could instead define it as { [k: string]: T | U } where U is the code path functions. But then you have another problem - if someone writes eg 'ClassDeclaration > ClassBody'(node) {...} then by your type definitions the type of that first argument must be Node | CodePathTypes and there's no way to assert your way out of that - which means the 99.9999% usecase for selectors is now poisoned and sucks.

So yeah - just not possible.

[overlookmotel]

TypeScript-ESLint gets around this by using a generic function

Ah ha! Thank you.

We also purposely don't define the code path selectors because (a) they're so so so so so rarely used and (b) it's impossible to make it work with TS.

Literally impossible? Or more like impossible without crazy complicated types? I'm no TS expert, but I assumed if you can write Doom in TS types, you should be able to define an object with some methods!

[bradzacher]

You can write an object with methods.
The problem is that TS only allows an index signature that matches all known properties on the object.

So if you define { [k: string]: T } then all known properties must also (a) have a string key, and (b) have a value that is assignable to T.

So if you define T = <N extends Node = never>(node: N) => Selectors, then that means that all the methods must match this shape!

Sadly the code path selectors are not assignable to this signature because their first parameter is the code path object and the second parameter is the node (which is non-optional ofc).

So you could instead define it as { [k: string]: T | U } where U us the code path functions (there are 3 signatures IIRC). But then that causes an issue - if someone defines a selector like, say, 'ClassDeclaration > ClassBody'(node) {...} then what is the type of node? Well based on your index signature the type is Parameters<T | U>[0] or Node | CodePathSelectorType. Which means that your node parameter can never be a node and there's no way to assert out of this case. Which means the 0.0000001% usecase of code path selectors has poisoned the 99.9999999% usecase of estree selectors and made their usage horrible.

[connorshea]

Can we just have an alternative type that can be imported which just drops the code path selector support? We would still support them if the user wants to use them, they'd just have to use the current, problematic type signature.

[bradzacher]

I guess put it this way. Rules essentially return HashMap<&str, FnMut(Node)>

No matter how hard you try you can't convert the map value to a FnMut(CodePath, Node) without going through some unsafe, poor DevX code on both sides.

We don't even bother exporting these signatures in typescript-eslint because it literally is a 1-in-a-million usecase. It's just not worth the hassle really. Optimise for the non-CodePath usecase and let the CodePath usecase be rough and ugly with as any.