feat(linter/plugins): introduce RuleTester

Author: overlookmotel

apps/oxlint/src-js/index.ts

@@ -1,6 +1,10 @@
 export { definePlugin, defineRule } from "./package/define.js";
+export { RuleTester } from "./package/rule_tester.js";
 
+// ESTree types
 export type * as ESTree from "./generated/types.d.ts";
+
+// Plugin types
 export type { Context, LanguageOptions } from "./plugins/context.ts";
 export type { Fix, Fixer, FixFn } from "./plugins/fix.ts";
 export type { CreateOnceRule, CreateRule, Plugin, Rule } from "./plugins/load.ts";
@@ -57,3 +61,22 @@ export type {
   Visitor,
   VisitorWithHooks,
 } from "./plugins/types.ts";
+
+// Rule tester types
+import type {
+  Config as _Config,
+  DescribeFn as _DescribeFn,
+  ItFn as _ItFn,
+  ValidTestCase as _ValidTestCase,
+  InvalidTestCase as _InvalidTestCase,
+  TestCases as _TestCases,
+} from "./package/rule_tester.ts";
+
+export namespace RuleTester {
+  export type Config = _Config;
+  export type DescribeFn = _DescribeFn;
+  export type ItFn = _ItFn;
+  export type ValidTestCase = _ValidTestCase;
+  export type InvalidTestCase = _InvalidTestCase;
+  export type TestCases = _TestCases;
+}

apps/oxlint/src-js/package/rule_tester.ts

@@ -0,0 +1,363 @@
+/*
+ * RuleTester class.
+ */
+
+import { default as assert, AssertionError } from "node:assert";
+import { inspect } from "node:util";
+import { registerPlugin, registeredRules } from "../plugins/load.js";
+import { lintFileImpl } from "../plugins/lint.js";
+
+import type { Plugin, Rule } from "../plugins/load.ts";
+
+// ------------------------------------------------------------------------------
+// `describe` and `it` functions
+// ------------------------------------------------------------------------------
+
+export type DescribeFn = <R>(text: string, method: () => R) => R;
+export type ItFn = (<R>(text: string, method: () => R) => R) & { only?: ItFn };
+
+declare global {
+  var describe: DescribeFn | undefined;
+  var it: ItFn | undefined;
+}
+
+/**
+ * Default `describe` function, if `describe` doesn't exist as a global.
+ * @param text - Description of the test case
+ * @param method - Test case logic
+ * @returns Returned value of `method`
+ */
+function defaultDescribe<R>(text: string, method: () => R): R {
+  return method.call(this);
+}
+
+// `describe` function. Can be overwritten via `RuleTester.describe` setter.
+let describe: DescribeFn =
+  typeof globalThis.describe === "function" ? globalThis.describe : defaultDescribe;
+
+/**
+ * Default `it` function, if `it` doesn't exist as a global.
+ * @param text - Description of the test case
+ * @param method - Test case logic
+ * @throws {Error} Any error upon execution of `method`
+ * @returns Returned value of `method`
+ */
+function defaultIt<R>(text: string, method: () => R): R {
+  try {
+    return method.call(this);
+  } catch (err) {
+    if (err instanceof AssertionError) {
+      err.message += ` (${inspect(err.actual)} ${err.operator} ${inspect(err.expected)})`;
+    }
+    throw err;
+  }
+}
+
+// `it` function. Can be overwritten via `RuleTester.it` setter.
+let it: ItFn = typeof globalThis.it === "function" ? globalThis.it : defaultIt;
+
+// `it.only` function. Can be overwritten via `RuleTester.it` or `RuleTester.itOnly` setters.
+let itOnly: ItFn | null =
+  it !== defaultIt && typeof it.only === "function" ? Function.bind.call(it.only, it) : null;
+
+/**
+ * Get `it` function.
+ * @param only - `true` if `it.only` should be used
+ * @returns `it` function
+ */
+function getIt(only?: boolean): ItFn {
+  return only ? getItOnly() : it;
+}
+
+/**
+ * Get `it.only` function.
+ * @param only - `true` if `it.only` should be used
+ * @returns `it` function
+ */
+function getItOnly(): ItFn {
+  if (itOnly === null) {
+    throw new Error(
+      "To use `only`, use `RuleTester` with a test framework that provides `it.only()` like Mocha, " +
+        "or provide a custom `it.only` function by assigning it to `RuleTester.itOnly`.",
+    );
+  }
+  return itOnly;
+}
+
+// ------------------------------------------------------------------------------
+// Config
+// ------------------------------------------------------------------------------
+
+/**
+ * Configuration for `RuleTester`.
+ */
+export interface Config {
+  rules: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+// Empty rules object
+const EMPTY_RULES = {};
+
+// Default shared config
+const DEFAULT_SHARED_CONFIG: Config = { rules: EMPTY_RULES };
+
+// `RuleTester` uses this config as its default. Can be overwritten via `RuleTester.setDefaultConfig()`.
+let sharedDefaultConfig: Config = DEFAULT_SHARED_CONFIG;
+
+// ------------------------------------------------------------------------------
+// Test cases
+// ------------------------------------------------------------------------------
+
+interface TestCase {
+  code: string;
+  name?: string;
+  only?: boolean;
+}
+
+/**
+ * Test case for valid code.
+ */
+export interface ValidTestCase extends TestCase {
+  before?: (this: ValidTestCase) => void;
+  after?: (this: ValidTestCase) => void;
+  // TODO
+}
+
+/**
+ * Test case for invalid code.
+ */
+export interface InvalidTestCase extends TestCase {
+  before?: (this: InvalidTestCase) => void;
+  after?: (this: InvalidTestCase) => void;
+  // TODO
+}
+
+/**
+ * Test cases for a rule.
+ */
+export interface TestCases {
+  valid: (ValidTestCase | string)[];
+  invalid: InvalidTestCase[];
+}
+
+// ------------------------------------------------------------------------------
+// `RuleTester` class
+// ------------------------------------------------------------------------------
+
+/**
+ * Utility class for testing rules.
+ */
+export class RuleTester {
+  /**
+   * Creates a new instance of RuleTester.
+   * @param config? - Extra configuration for the tester (optional)
+   */
+  constructor(config?: Config) {
+    // TODO: Merge this into config used for tests
+    const _ = config;
+  }
+
+  /**
+   * Set the configuration to use for all future tests.
+   * @param config - The configuration to use
+   * @throws {TypeError} If `config` is not an object
+   */
+  static setDefaultConfig(config: Config): void {
+    if (typeof config !== "object" || config === null) {
+      throw new TypeError("`config` must be an object");
+    }
+    sharedDefaultConfig = config;
+
+    // Make sure the rules object exists since it is assumed to exist later
+    if (sharedDefaultConfig.rules == null) sharedDefaultConfig.rules = EMPTY_RULES;
+  }
+
+  /**
+   * Get the current configuration used for all tests.
+   * @returns The current configuration
+   */
+  static getDefaultConfig(): Config {
+    return sharedDefaultConfig;
+  }
+
+  /**
+   * Reset the configuration to the initial configuration of the tester removing
+   * any changes made until now.
+   * @returns {void}
+   */
+  static resetDefaultConfig() {
+    sharedDefaultConfig = DEFAULT_SHARED_CONFIG;
+  }
+
+  // Getters/setters for `describe` and `it` functions
+
+  static get describe(): DescribeFn {
+    return describe;
+  }
+
+  static set describe(value: DescribeFn) {
+    describe = value;
+  }
+
+  static get it(): ItFn {
+    return it;
+  }
+
+  static set it(value: ItFn) {
+    it = value;
+    if (typeof it.only === "function") {
+      itOnly = Function.bind.call(it.only, it);
+    } else {
+      itOnly = null;
+    }
+  }
+
+  static get itOnly(): ItFn {
+    return getItOnly();
+  }
+
+  static set itOnly(value: ItFn) {
+    itOnly = value;
+  }
+
+  /**
+   * Add the `only` property to a test to run it in isolation.
+   * @param item - A single test to run by itself
+   * @returns The test with `only` set
+   */
+  static only(item: string | ValidTestCase | InvalidTestCase): ValidTestCase | InvalidTestCase {
+    if (typeof item === "string") return { code: item, only: true };
+    return { ...item, only: true };
+  }
+
+  /**
+   * Adds a new rule test to execute.
+   * @param ruleName - Name of the rule to run
+   * @param rule - Rule to test
+   * @param tests - Collection of tests to run
+   * @throws {TypeError|Error} If `rule` is not an object with a `create` method,
+   *   or if non-object `test`, or if a required scenario of the given type is missing
+   */
+  run(ruleName: string, rule: Rule, tests: TestCases): void {
+    // TODO
+    let _ = tests;
+
+    // Reset registered rules, so this rule is registered as rule 0
+    registeredRules.length = 0;
+
+    // Register the rule
+    const plugin: Plugin = {
+      meta: {
+        name: "rule-to-test",
+      },
+      rules: {
+        [ruleName]: rule,
+      },
+    };
+    registerPlugin(plugin, null);
+
+    // TODO: Create buffer
+    const path = "file.js",
+      bufferId = 0,
+      buffer = null,
+      ruleIds = [0],
+      optionsIds = [0],
+      settingsJSON = "{}";
+
+    describe(ruleName, () => {
+      if (tests.valid.length > 0) {
+        describe("valid", () => {
+          const _seenTestCases = new Set();
+          for (let test of tests.valid) {
+            if (typeof test === "string") test = { code: test };
+
+            const it = getIt(test.only);
+            it(getTestName(test), () => {
+              try {
+                runHook(test, "before");
+
+                // assertValidTestCase(item, seenTestCases);
+                // testValidTemplate(item);
+
+                // TODO: Write `code` to buffer
+
+                lintFileImpl(path, bufferId, buffer, ruleIds, optionsIds, settingsJSON);
+
+                // TODO: Check diagnostics
+              } finally {
+                runHook(test, "after");
+              }
+            });
+          }
+        });
+      }
+
+      if (tests.invalid.length > 0) {
+        describe("invalid", () => {
+          const _seenTestCases = new Set();
+          for (const test of tests.invalid) {
+            const it = getIt(test.only);
+            it(getTestName(test), () => {
+              try {
+                runHook(test, "before");
+                // assertInvalidTestCase(item, seenTestCases, ruleName);
+                // testInvalidTemplate(item);
+
+                // TODO: Write `code` to buffer
+
+                lintFileImpl(path, bufferId, buffer, ruleIds, optionsIds, settingsJSON);
+
+                // TODO: Check diagnostics
+              } finally {
+                runHook(test, "after");
+              }
+            });
+          }
+        });
+      }
+    });
+  }
+}
+
+/**
+ * Get name of test case.
+ * @param test - Test case
+ * @returns Name of test case
+ */
+function getTestName(test: TestCase): string {
+  return sanitize(test.name || test.code);
+}
+
+/**
+ * Replace control characters with `\u00xx` form.
+ * @param text - Text to sanitize
+ * @returns Sanitized text
+ */
+function sanitize(text: string): string {
+  if (typeof text !== "string") return "";
+  return text.replace(
+    /[\u0000-\u0009\u000b-\u001a]/gu, // oxlint-disable-line no-control-regex -- Escaping controls
+    (c) => `\\u${c.codePointAt(0)!.toString(16).padStart(4, "0")}`,
+  );
+}
+
+/**
+ * Runs a hook on the given test case.
+ * @param test - Test to run the hook on
+ * @param prop - Hook type
+ * @throws {Error} - If the property is not a function or that function throws an error
+ */
+function runHook<T extends ValidTestCase | InvalidTestCase>(
+  test: T,
+  prop: "before" | "after",
+): void {
+  if (Object.hasOwn(test, prop)) {
+    assert.strictEqual(
+      typeof test[prop],
+      "function",
+      `Optional test case property \`${prop}\` must be a function`,
+    );
+    test[prop]!();
+  }
+}