feat(linter/plugins): oxlint export types (#14163)

`oxlint` package export TS types. `defineRule` and `definePlugin` now give you type-safety and intellisense.

Writing plugins in TS is only supported on versions of NodeJS which support type-stripping. Have not added a library (e.g. Jiti) to support older NodeJS versions.

Probably some of the types are wrong, or incomplete, and we should maybe export more types. But I think this is a decent start.

Author: overlookmotel

apps/oxlint/package.json

@@ -4,6 +4,7 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": "dist/cli.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "build": "pnpm run build-napi-release && pnpm run build-js",
     "build-dev": "pnpm run build-napi && pnpm run build-js",
@@ -34,9 +35,13 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@oxc-project/types": "workspace:^"
+  },
   "devDependencies": {
     "eslint": "^9.36.0",
     "execa": "^9.6.0",
+    "jiti": "^2.6.0",
     "tsdown": "0.15.1",
     "typescript": "catalog:",
     "vitest": "catalog:"

apps/oxlint/src-js/index.ts

@@ -2,6 +2,11 @@ import type { Context } from './plugins/context.ts';
 import type { CreateOnceRule, Plugin, Rule } from './plugins/load.ts';
 import type { BeforeHook, Visitor, VisitorWithHooks } from './plugins/types.ts';
 
+export type { Context, Diagnostic } from './plugins/context.ts';
+export type { Fix, Fixer, FixFn, NodeOrToken, Range } from './plugins/fix.ts';
+export type { CreateOnceRule, CreateRule, Plugin, Rule } from './plugins/load.ts';
+export type { AfterHook, BeforeHook, RuleMeta, Visitor, VisitorWithHooks } from './plugins/types.ts';
+
 const { defineProperty, getPrototypeOf, hasOwn, setPrototypeOf, create: ObjectCreate } = Object;
 
 const dummyOptions: unknown[] = [],

apps/oxlint/src-js/plugins/fix.ts

@@ -17,10 +17,10 @@ export type FixFn = (
 // Type of a fix, as returned by `fix` function.
 export type Fix = { range: Range; text: string };
 
-type Range = [number, number];
+export type Range = [number, number];
 
 // Currently we only support `Node`s, but will add support for `Token`s later
-interface NodeOrToken {
+export interface NodeOrToken {
   start: number;
   end: number;
 }
@@ -60,7 +60,7 @@ const FIXER = Object.freeze({
   },
 });
 
-type Fixer = typeof FIXER;
+export type Fixer = typeof FIXER;
 
 /**
  * Get fixes from a `Diagnostic`.

apps/oxlint/src-js/plugins/load.ts

@@ -20,7 +20,7 @@ export interface Plugin {
 // If `createOnce` method is present, `create` is ignored.
 export type Rule = CreateRule | CreateOnceRule;
 
-interface CreateRule {
+export interface CreateRule {
   meta?: RuleMeta;
   create: (context: Context) => Visitor;
 }

apps/oxlint/test/fixtures/definePlugin/.oxlintrc.json

@@ -1,5 +1,5 @@
 {
-  "jsPlugins": ["./plugin.js"],
+  "jsPlugins": ["./plugin.ts"],
   "categories": { "correctness": "off" },
   "rules": {
     "define-plugin-plugin/create": "error",

apps/oxlint/test/fixtures/definePlugin/eslint.config.js

@@ -1,4 +1,4 @@
-import plugin from './plugin.js';
+import plugin from './plugin.ts';
 
 export default [
   {

apps/oxlint/test/fixtures/definePlugin/plugin.js renamed to apps/oxlint/test/fixtures/definePlugin/plugin.ts

@@ -1,5 +1,6 @@
 import { sep } from 'node:path';
 import { definePlugin } from '../../../dist/index.js';
+import type { Rule } from '../../../dist/index.js';
 
 // `loc` is required for ESLint
 const SPAN = {
@@ -14,10 +15,10 @@ const SPAN = {
 const DIR_PATH_LEN = import.meta.dirname.length + 1;
 
 const relativePath = sep === '/'
-  ? path => path.slice(DIR_PATH_LEN)
-  : path => path.slice(DIR_PATH_LEN).replace(/\\/g, '/');
+  ? (path: string) => path.slice(DIR_PATH_LEN)
+  : (path: string) => path.slice(DIR_PATH_LEN).replace(/\\/g, '/');
 
-const createRule = {
+const createRule: Rule = {
   create(context) {
     context.report({ message: `create body:\nthis === rule: ${this === createRule}`, node: SPAN });
 
@@ -37,18 +38,19 @@ const createRule = {
 // adds to the rule.
 let createOnceCallCount = 0;
 
-const createOnceRule = {
+const createOnceRule: Rule = {
   createOnce(context) {
     createOnceCallCount++;
 
     // `fileNum` should be different for each file.
     // `identNum` should start at 1 for each file.
-    let fileNum = 0, identNum;
+    let fileNum = 0, identNum: number;
     // Note: Files are processed in unpredictable order, so `files/1.js` may be `fileNum` 1 or 2.
     // Therefore, collect all visits and check them in `after` hook of the 2nd file.
-    const visits = [];
+    const visits: { fileNum: number; identNum: number }[] = [];
 
     // `this` should be the rule object
+    // oxlint-disable-next-line typescript-eslint/no-this-alias
     const topLevelThis = this;
 
     return {
@@ -106,7 +108,7 @@ const createOnceRule = {
 };
 
 // Tests that `before` hook returning `false` disables visiting AST for the file.
-const createOnceBeforeFalseRule = {
+const createOnceBeforeFalseRule: Rule = {
   createOnce(context) {
     return {
       before() {
@@ -139,7 +141,7 @@ const createOnceBeforeFalseRule = {
 
 // These 3 rules test that `createOnce` without `before` and `after` hooks works correctly.
 
-const createOnceBeforeOnlyRule = {
+const createOnceBeforeOnlyRule: Rule = {
   createOnce(context) {
     return {
       before() {
@@ -160,7 +162,7 @@ const createOnceBeforeOnlyRule = {
   },
 };
 
-const createOnceAfterOnlyRule = {
+const createOnceAfterOnlyRule: Rule = {
   createOnce(context) {
     return {
       Identifier(node) {
@@ -181,7 +183,7 @@ const createOnceAfterOnlyRule = {
   },
 };
 
-const createOnceNoHooksRule = {
+const createOnceNoHooksRule: Rule = {
   createOnce(context) {
     return {
       Identifier(node) {

apps/oxlint/test/fixtures/definePlugin_and_defineRule/.oxlintrc.json

@@ -1,5 +1,5 @@
 {
-  "jsPlugins": ["./plugin.js"],
+  "jsPlugins": ["./plugin.ts"],
   "categories": { "correctness": "off" },
   "rules": {
     "define-plugin-and-rule-plugin/create": "error",

apps/oxlint/test/fixtures/definePlugin_and_defineRule/eslint.config.js

@@ -1,4 +1,4 @@
-import plugin from './plugin.js';
+import plugin from './plugin.ts';
 
 export default [
   {

apps/oxlint/test/fixtures/definePlugin_and_defineRule/plugin.js renamed to apps/oxlint/test/fixtures/definePlugin_and_defineRule/plugin.ts

@@ -14,8 +14,8 @@ const SPAN = {
 const DIR_PATH_LEN = import.meta.dirname.length + 1;
 
 const relativePath = sep === '/'
-  ? path => path.slice(DIR_PATH_LEN)
-  : path => path.slice(DIR_PATH_LEN).replace(/\\/g, '/');
+  ? (path: string) => path.slice(DIR_PATH_LEN)
+  : (path: string) => path.slice(DIR_PATH_LEN).replace(/\\/g, '/');
 
 const createRule = defineRule({
   create(context) {
@@ -42,12 +42,13 @@ const createOnceRule = defineRule({
 
     // `fileNum` should be different for each file.
     // `identNum` should start at 1 for each file.
-    let fileNum = 0, identNum;
+    let fileNum = 0, identNum: number;
     // Note: Files are processed in unpredictable order, so `files/1.js` may be `fileNum` 1 or 2.
     // Therefore, collect all visits and check them in `after` hook of the 2nd file.
-    const visits = [];
+    const visits: { fileNum: number; identNum: number }[] = [];
 
     // `this` should be the rule object returned by `defineRule`
+    // oxlint-disable-next-line typescript-eslint/no-this-alias
     const topLevelThis = this;
 
     return {