feat(linter/plugins): add defineRule API

Author: overlookmotel

apps/oxlint/package.json

@@ -1,6 +1,7 @@
 {
   "name": "oxlint",
   "version": "1.16.0",
+  "main": "dist/index.js",
   "bin": "dist/cli.js",
   "type": "module",
   "scripts": {

apps/oxlint/src-js/index.ts

@@ -0,0 +1,59 @@
+import type { Context } from './plugins/context.ts';
+import type { Rule } from './plugins/load.ts';
+
+const { defineProperty, getPrototypeOf, setPrototypeOf } = Object;
+
+const dummyOptions: unknown[] = [],
+  dummyReport = () => {};
+
+// Define a rule.
+// If rule has `createOnce` method, add an ESLint-compatible `create` method which delegates to `createOnce`.
+export function defineRule(rule: Rule): Rule {
+  if (!('createOnce' in rule)) return rule;
+  if ('create' in rule) throw new Error('Rules must define only `create` or `createOnce` methods, not both');
+
+  // Run `createOnce` with empty context object.
+  // Really, `context` should be an instance of `Context`, which would throw error on accessing e.g. `id`
+  // in body of `createOnce`. But any such bugs should have been caught when testing the rule in Oxlint,
+  // so should be OK to take this shortcut.
+  const context = Object.create(null, {
+    id: { value: '', enumerable: true, configurable: true },
+    options: { value: dummyOptions, enumerable: true, configurable: true },
+    report: { value: dummyReport, enumerable: true, configurable: true },
+  });
+
+  const { before: beforeHook, after: afterHook, ...visitor } = rule.createOnce(context as Context);
+
+  // Add `after` hook to `Program:exit` visit fn
+  if (afterHook !== null) {
+    const programExit = visitor['Program:exit'];
+    visitor['Program:exit'] = programExit
+      ? (node) => {
+        programExit(node);
+        afterHook();
+      }
+      : (_node) => afterHook();
+  }
+
+  // Create `create` function
+  rule.create = (eslintContext) => {
+    // Copy properties from ESLint's context object to `context`.
+    // ESLint's context object is an object of form `{ id, options, report }`, with all other properties
+    // and methods on another object which is its prototype.
+    defineProperty(context, 'id', { value: eslintContext.id });
+    defineProperty(context, 'options', { value: eslintContext.options });
+    defineProperty(context, 'report', { value: eslintContext.report });
+    setPrototypeOf(context, getPrototypeOf(eslintContext));
+
+    // If `before` hook returns `false`, skip rest of traversal by returning an empty object as visitor
+    if (beforeHook !== null) {
+      const shouldRun = beforeHook();
+      if (shouldRun === false) return {};
+    }
+
+    // Return same visitor each time
+    return visitor;
+  };
+
+  return rule;
+}

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

@@ -16,13 +16,13 @@ interface Plugin {
 // Linter rule.
 // `Rule` can have either `create` method, or `createOnce` method.
 // If `createOnce` method is present, `create` is ignored.
-type Rule = CreateRule | CreateOnceRule;
+export type Rule = CreateRule | CreateOnceRule;
 
 interface CreateRule {
   create: (context: Context) => Visitor;
 }
 
-interface CreateOnceRule {
+export interface CreateOnceRule {
   create?: (context: Context) => Visitor;
   createOnce: (context: Context) => VisitorWithHooks;
 }

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

@@ -0,0 +1,9 @@
+{
+    "plugins": ["./test_plugin"],
+    "categories": {"correctness": "off"},
+    "rules": {
+        "define-rule-plugin/create": "error",
+        "define-rule-plugin/create-once": "error"
+    },
+    "ignorePatterns": ["test_plugin/**"]
+}

apps/oxlint/test/fixtures/defineRule/files/1.js

@@ -0,0 +1 @@
+let a, b;

apps/oxlint/test/fixtures/defineRule/files/2.js

@@ -0,0 +1 @@
+let c, d;

apps/oxlint/test/fixtures/defineRule/test_plugin/index.js

@@ -0,0 +1,72 @@
+import { dirname, sep } from 'node:path';
+import { defineRule } from 'oxlint';
+
+const SPAN = { start: 0, end: 0 };
+
+const PARENT_DIR_PATH_LEN = dirname(import.meta.dirname).length + 1;
+
+const relativePath = sep === '/'
+  ? path => path.slice(PARENT_DIR_PATH_LEN)
+  : path => path.slice(PARENT_DIR_PATH_LEN).replace(/\\/g, '/');
+
+const createRule = defineRule({
+  create(context) {
+    return {
+      Identifier(node) {
+        context.report({
+          message: `ident visit fn "${node.name}": filename: ${relativePath(context.filename)}`,
+          node,
+        });
+      },
+    };
+  },
+});
+
+const createOnceRule = defineRule({
+  createOnce(context) {
+    // `fileNum` should be different for each file.
+    // `identNum` should start at 1 for each file.
+    let fileNum = 0, identNum;
+    return {
+      before() {
+        fileNum++;
+        identNum = 0;
+        context.report({
+          message: 'before hook:\n'
+            + `fileNum: ${fileNum}\n`
+            + `filename: ${relativePath(context.filename)}`,
+          node: SPAN,
+        });
+      },
+      Identifier(node) {
+        identNum++;
+        context.report({
+          message: `ident visit fn "${node.name}":\n`
+            + `fileNum: ${fileNum}\n`
+            + `identNum: ${identNum}\n`
+            + `filename: ${relativePath(context.filename)}`,
+          node,
+        });
+      },
+      after() {
+        context.report({
+          message: 'after hook:\n'
+            + `fileNum: ${fileNum}\n`
+            + `identNum: ${identNum}\n`
+            + `filename: ${relativePath(context.filename)}`,
+          node: SPAN,
+        });
+      },
+    };
+  },
+});
+
+export default {
+  meta: {
+    name: "define-rule-plugin",
+  },
+  rules: {
+    create: createRule,
+    "create-once": createOnceRule,
+  },
+};

apps/oxlint/tsdown.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsdown';
 
 export default defineConfig({
-  entry: ['src-js/cli.ts', 'src-js/plugins/index.ts'],
+  entry: ['src-js/index.ts', 'src-js/cli.ts', 'src-js/plugins/index.ts'],
   format: ['esm'],
   platform: 'node',
   target: 'node20',

npm/oxlint/package.json

@@ -13,6 +13,7 @@
     "url": "git+https://github.com/oxc-project/oxc",
     "directory": "npm/oxlint"
   },
+  "main": "dist/index.js",
   "bin": {
     "oxlint": "bin/oxlint",
     "oxc_language_server": "bin/oxc_language_server"