eslint-plugin-ore-ui

An ESLint plugin to be used on Minecraft Bedrock Edition Ore UI scripts.

Installation

Install ESLint if you haven't already:

npm i eslint --save-dev

Install the plugin:

npm i eslint-plugin-ore-ui --save-dev

Usage

Flat Config

Here are several examples of flat configs using this plugin:

// eslint.config.js
import oreUIPlugin from "eslint-plugin-ore-ui";

export default [
    // Enables the plugin and enables the recommended config (without type checking).
    oreUIPlugin.flatConfigs.recommended,
];

// eslint.config.js
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";
import oreUIPlugin from "eslint-plugin-ore-ui";

export default defineConfig(
    // Enables the typescript-eslint plugin and enables the recommended config for it (with type checking).
    tseslint.configs.recommendedTypeChecked,
    // Enables the plugin and enables the recommended config (with type checking).
    oreUIPlugin.flatConfigs.recommendedTypeChecked,
    {
        languageOptions: {
            ecmaVersion: "latest",
            sourceType: "module",
            globals: {
                ...globals.es2015,
                ...globals.node,
            },
            parser: tseslint.parser,
            parserOptions: {
                // Required: Without this, the type checked options will throw errors.
                projectService: true,
            },
        },
    }
);

// eslint.config.mts
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";
import oreUIPlugin from "eslint-plugin-ore-ui";

export default defineConfig(
    // Enables the typescript-eslint plugin and enables the recommended config for it (with type checking).
    tseslint.configs.recommendedTypeChecked,
    // Enables the plugin and enables the recommended config (with type checking).
    oreUIPlugin.flatConfigs.recommendedTypeChecked,
    {
        languageOptions: {
            ecmaVersion: "latest",
            sourceType: "module",
            globals: {
                ...globals.es2015,
                ...globals.node,
            },
            parser: tseslint.parser,
            parserOptions: {
                // Required: Without this, the type checked options will throw errors.
                projectService: true,
            },
        },
    }
);

// eslint.config.cjs
const { defineConfig } = require("eslint/config");
const tseslint = require("typescript-eslint");
const oreUIPlugin = require("eslint-plugin-ore-ui");

module.exports = defineConfig([
    // Enables the typescript-eslint plugin and enables the recommended config for it (with type checking).
    tseslint.configs.recommendedTypeChecked,
    // Enables the plugin and enables the recommended config (with type checking).
    oreUIPlugin.flatConfigs.recommendedTypeChecked,
    {
        languageOptions: {
            ecmaVersion: "latest",
            sourceType: "module",
            globals: {
                ...globals.es2015,
                ...globals.node,
            },
            // Required: Without this, the type checked options will throw errors.
            parser: tseslint.parser,
            parserOptions: {
                // Required: Without this, the type checked options will throw errors.
                projectService: true,
            },
        },
    },
    {
        files: ["*.js", "*.cjs", "*.mjs"],
        // Disables the type checked rules on JS files.
        extends: [tseslint.configs.disableTypeChecked, oreUIPlugin.flatConfigs.disableTypeChecked],
        languageOptions: {
            parserOptions: {
                projectService: false,
            },
        },
    },
]);

Legacy Config

Here are four examples of legacy configs using this plugin:

// .eslintrc.json
{
    "extends": [
        // Enables the plugin and enables the recommended config (without type checking).
        "plugin:ore-ui/recommended"
    ]
}

// .eslintrc
{
    "extends": [
        // Enables the typescript-eslint plugin and enables the recommended config for it (with type checking).
        "plugin:@typescript-eslint/recommended-type-checked",
        // Enables the plugin and enables the recommended config (with type checking).
        "plugin:ore-ui/recommended-type-checked"
    ],
    // Required for type checked rules.
    "parser": "@typescript-eslint/parser",
    "root": true,
    "parserOptions": {
        // Required for type checked rules.
        "project": true
    }
}

// .eslintrc
{
    // Required for type checked rules.
    "parser": "@typescript-eslint/parser",
    "plugins": [
        // Enables the typescript-eslint plugin.
        "@typescript-eslint/eslint-plugin",
        // Enables the plugin.
        "ore-ui",
        // Enabled the no-import-attributes plugin.
        "no-import-attributes"
    ],
    "rules": {
        // Configures the recommended type checked options.
        "no-import-attributes/no-import-attributes": ["error", "Import attributes are not supported by CoHTML (Ore UI)."],
        "ore-ui/no-illegal-constructors": "error",
        "ore-ui/no-bugged": "warn",
        "ore-ui/no-critically-bugged": "error",
        "ore-ui/no-regex-unicode-properties": "warn",
        "ore-ui/no-regex-v-flag": "error",
        "ore-ui/no-using-keyword": "error"
    },
    "root": true,
    "parserOptions": {
        // Required for type checked rules.
        "project": true
    }
}

// .eslintrc.cjs
/* eslint-env node */
import {} from "eslint-plugin-ore-ui";
module.exports = {
    extends: ["plugin:ore-ui/recommended"],
    rules: {
        // Disables the `ore-ui/no-regex-unicode-properties` rule.
        "ore-ui/no-regex-unicode-properties": "off",
    },
};

Rules

ore-ui/no-illegal-constructors

Disallow using constructing constructors marked as being an illegal constructor.

Options

This rule accepts the following options:

type Options = [
    {
        /** Type specifiers that can be allowed. */
        allow?: (
            | {
                  from: "file";
                  name: string | string[];
                  path?: string;
              }
            | {
                  from: "lib";
                  name: string | string[];
              }
            | {
                  from: "package";
                  name: string | string[];
                  package: string;
              }
            | string
        )[];
        /** Whether to ignore the built-in illegal constructor messages. */
        ignoreBuiltInIllegalConstructorMessages?: boolean;
        /** Additional illegal constructor messages to check for. */
        additionalIllegalConstructorMessages?: IllegalConstructorMessage[];
    },
];

interface IllegalConstructorMessage {
    /** The message to filter JSDoc comments by, only matching JSDoc comments will cause a violation. If not provided, any JSDoc tag of the specified name will cause a violation. */
    message?:
        | string
        | {
              regex: string;
              flags?: string;
          };
    /** The JSDoc tag name or a list of JSDoc tag names to filter by, should not be prefixed with '@'. ex. 'throws' */
    tagName: string | string[];
    /** The reason for the violation, this is what will be reported. ex. If the reason is 'This is only constructable by the engine itself.', the message will be '`{{name}}` is an illegal constructor. This is only constructable by the engine itself.' */
    reason?: string;
    /** The error message to report. This will take precedence over `reason`. Unlike reason, this does not prepend '`{{name}}` is an illegal constructor.' to the reason. ex. If the reason override is 'This is only constructable by the engine itself.', the message will be 'This is only constructable by the engine itself.' */
    reasonOverride?: string;
}

const defaultOptions: Options = [
    {
        allow: [],
        ignoreBuiltInIllegalConstructorMessages: false,
        additionalIllegalConstructorMessages: [],
    },
];

const builtInIllegalConstructorMessages: IllegalConstructorMessage[] = [
    {
        message: {
            regex: "^(?:\\{[^\\}]*\\} )?Throws an [`\"']Illegal constructor[`\"'] error as this is only constructable by the engine itself\\.",
            flags: "",
        },
        tagName: "throws",
        reason: "This is only constructable by the engine itself.",
    },
    {
        message: {
            regex: "^(?:\\{[^\\}]*\\} )?\\(BROWSER ONLY\\) Throws an [`\"']Illegal constructor[`\"'] error as this is only constructable by the engine itself\\.",
            flags: "",
        },
        tagName: "throws",
        reason: "In the browser, this is only constructable by the engine itself.",
    },
];

ore-ui/no-bugged

Disallow bugged symbols.

Options

This rule accepts the following options:

type Options = [
    {
        /** Type specifiers that can be allowed. */
        allow?: (
            | {
                  from: "file";
                  name: string | string[];
                  path?: string;
              }
            | {
                  from: "lib";
                  name: string | string[];
              }
            | {
                  from: "package";
                  name: string | string[];
                  package: string;
              }
            | string
        )[];
        /** Whether to ignore the built-in bugged messages. */
        ignoreBuiltInBuggedMessages?: boolean;
        /** Additional bugged messages to check for. */
        additionalBuggedMessages?: BuggedMessage[];
    },
];

type StringOrRegExpFilterItem =
    | string
    | {
          regex: string;
          flags?: string;
      };

type StringOrRegExpFilter = StringOrRegExpFilterItem | StringOrRegExpFilterItem[];

interface BuggedMessage {
    /** The message to filter JSDoc comments by, only matching JSDoc comments will cause a violation. If not provided, any JSDoc tag of the specified name will cause a violation. */
    message?: StringOrRegExpFilterItem;
    /** The prefix filtering options, these are used to find the start of the bug description, only matching JSDoc comments will cause a violation. */
    prefix:
        | {
              /** The JSDoc tag name or a list of JSDoc tag names to filter by, should not be prefixed with '@'. ex. 'throws' */
              tagName: StringOrRegExpFilter;
          }
        | {
              /** The prefix to filter by, this is text that would be at the start of a line in the JSDoc, immediately followed by a colon, should not be suffixed with a colon. ex. 'Critical Bug' or 'Bug!!' */
              prefix: StringOrRegExpFilter;
          }
        | {
              /** The JSDoc tag name or a list of JSDoc tag names to filter by, should not be prefixed with '@'. ex. 'throws' */
              tagName: StringOrRegExpFilter;
              /** The prefix to filter by, this is text that would be at the start of a line in the JSDoc, immediately followed by a colon, should not be suffixed with a colon. ex. 'Critical Bug' or 'Bug!!' */
              prefix: StringOrRegExpFilter;
          };
    /** The reason for the violation, this is what will be reported, if not specified, the message will be the bug description. ex. If the reason is 'This does not work at all in CoHTML (Ore UI).', the message will be '`{{name}}` has a bug. This does not work at all in CoHTML (Ore UI).' */
    reason?: string;
    /** The error message to report. This will take precedence over `reason`. Unlike reason, this does not prepend '`{{name}}` has a bug.' to the reason. ex. If the reason override is 'This does not work at all in CoHTML (Ore UI).', the message will be 'This does not work at all in CoHTML (Ore UI).' */
    reasonOverride?: string;
}

const defaultOptions: Options = [
    {
        allow: [],
        ignoreBuiltInBuggedMessages: false,
        additionalBuggedMessages: [],
    },
];

const builtInBuggedMessages: BuggedMessage[] = [
    {
        prefix: {
            tagName: [
                { regex: "^bugged1$", flags: "i" },
                { regex: "^bug1$", flags: "i" },
            ],
            prefix: ["Bug!", "!Bug"],
        },
    },
];

ore-ui/no-critically-bugged

Disallow critically bugged symbols.

Options

This rule accepts the following options:

type Options = [
    {
        /** Type specifiers that can be allowed. */
        allow?: (
            | {
                  from: "file";
                  name: string | string[];
                  path?: string;
              }
            | {
                  from: "lib";
                  name: string | string[];
              }
            | {
                  from: "package";
                  name: string | string[];
                  package: string;
              }
            | string
        )[];
        /** Whether to ignore the built-in critically bugged messages. */
        ignoreBuiltInCriticallyBuggedMessages?: boolean;
        /** Additional critically bugged messages to check for. */
        additionalCriticallyBuggedMessages?: CriticallyBuggedMessage[];
    },
];

type StringOrRegExpFilterItem =
    | string
    | {
          regex: string;
          flags?: string;
      };

type StringOrRegExpFilter = StringOrRegExpFilterItem | StringOrRegExpFilterItem[];

interface CriticallyBuggedMessage {
    /** The message to filter JSDoc comments by, only matching JSDoc comments will cause a violation. If not provided, any JSDoc tag of the specified name will cause a violation. */
    message?: StringOrRegExpFilterItem;
    /** The prefix filtering options, these are used to find the start of the bug description, only matching JSDoc comments will cause a violation. */
    prefix:
        | {
              /** The JSDoc tag name or a list of JSDoc tag names to filter by, should not be prefixed with '@'. ex. 'throws' */
              tagName: StringOrRegExpFilter;
          }
        | {
              /** The prefix to filter by, this is text that would be at the start of a line in the JSDoc, immediately followed by a colon, should not be suffixed with a colon. ex. 'Critical Bug' or 'Bug!!' */
              prefix: StringOrRegExpFilter;
          }
        | {
              /** The JSDoc tag name or a list of JSDoc tag names to filter by, should not be prefixed with '@'. ex. 'throws' */
              tagName: StringOrRegExpFilter;
              /** The prefix to filter by, this is text that would be at the start of a line in the JSDoc, immediately followed by a colon, should not be suffixed with a colon. ex. 'Critical Bug' or 'Bug!!' */
              prefix: StringOrRegExpFilter;
          };
    /** The reason for the violation, this is what will be reported, if not specified, the message will be the bug description. ex. If the reason is 'This does not work at all in CoHTML (Ore UI).', the message will be '`{{name}}` has a critical bug. This does not work at all in CoHTML (Ore UI).' */
    reason?: string;
    /** The error message to report. This will take precedence over `reason`. Unlike reason, this does not prepend '`{{name}}` has a critical bug.' to the reason. ex. If the reason override is 'This does not work at all in CoHTML (Ore UI).', the message will be 'This does not work at all in CoHTML (Ore UI).' */
    reasonOverride?: string;
}

const defaultOptions: Options = [
    {
        allow: [],
        ignoreBuiltInCriticallyBuggedMessages: false,
        additionalCriticallyBuggedMessages: [],
    },
];

const builtInCriticallyBuggedMessages: CriticallyBuggedMessage[] = [
    {
        prefix: {
            tagName: [
                { regex: "^criticallyBugged$", flags: "i" },
                { regex: "^criticalBug$", flags: "i" },
                { regex: "^bugged2$", flags: "i" },
                { regex: "^bug2$", flags: "i" },
            ],
            prefix: ["Critical Bug", "Bug (Critical)", "Bug!!", "!!Bug"],
        },
    },
];

ore-ui/no-regex-unicode-properties

Disallow regex Unicode property escapes.

Options

This rule is not configurable.

ore-ui/no-regex-v-flag

Disallow the v regex flag.

Options

This rule is not configurable.

ore-ui/no-using-keyword

Disallow the using keyword.

Options

type Options = [
    {
        /** Types of using variable declarations that can be allowed. Should be one of `using` or `await using`. Defaults to an empty array. */
        allow?: ("using" | "await using")[];
    },
];

const defaultOptions: Options = [
    {
        allow: [],
    },
];

Configs

ore-ui/recommended

The recommended config when not using type checked rules.

Legacy Config ID: plugin:ore-ui/recommended
Flat Config Property Path: plugin.flatConfigs.recommended

const plugins = [
    // This plugin.
    "ore-ui",
    // The `no-import-attributes` plugin (`eslint-plugin-no-import-attributes` on NPM).
    "no-import-attributes",
];

const rules = {
    "no-import-attributes/no-import-attributes": ["error", "Import attributes are not supported by CoHTML (Ore UI)."],
    "ore-ui/no-illegal-constructors": "off",
    "ore-ui/no-bugged": "off",
    "ore-ui/no-critically-bugged": "off",
    "ore-ui/no-regex-unicode-properties": "warn",
    "ore-ui/no-regex-v-flag": "error",
    "ore-ui/no-using-keyword": "error",
};

ore-ui/recommended-type-checked

The recommended config when using type checked rules.

Legacy Config ID: plugin:ore-ui/recommended-type-checked
Flat Config Property Path: plugin.flatConfigs.recommendedTypeChecked

const plugins = [
    // This plugin.
    "ore-ui",
    // The `no-import-attributes` plugin (`eslint-plugin-no-import-attributes` on NPM).
    "no-import-attributes",
];

const rules = {
    "no-import-attributes/no-import-attributes": ["error", "Import attributes are not supported by CoHTML (Ore UI)."] as const,
    "ore-ui/no-illegal-constructors": "error",
    "ore-ui/no-bugged": "warn",
    "ore-ui/no-critically-bugged": "error",
    "ore-ui/no-regex-unicode-properties": "warn",
    "ore-ui/no-regex-v-flag": "error",
    "ore-ui/no-using-keyword": "error",
};

ore-ui/disable-type-checked

Disable type checked rules.

Legacy Config ID: plugin:ore-ui/disable-type-checked
Flat Config Property Path: plugin.flatConfigs.disableTypeChecked

const rules = {
    "ore-ui/no-illegal-constructors": "off",
    "ore-ui/no-bugged": "off",
    "ore-ui/no-critically-bugged": "off",
};