eslint-plugin-ore-ui 1.0.0

package/Changelog.md

@@ -0,0 +1,3 @@
+# v1.0.0
+
+-   Initial Release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8Crafter Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,604 @@
+# eslint-plugin-ore-ui
+
+<!-- ![Thumbnail](./assets/thumbnail.png) --> <!-- TODO -->
+
+[![NPM Downloads](https://img.shields.io/npm/d18m/eslint-plugin-ore-ui)](https://npmjs.com/package/eslint-plugin-ore-ui)
+[![NPM Version](https://img.shields.io/npm/v/eslint-plugin-ore-ui)](https://npmjs.com/package/eslint-plugin-ore-ui)
+[![NPM License](https://img.shields.io/npm/l/eslint-plugin-ore-ui)](https://npmjs.com/package/eslint-plugin-ore-ui)
+[![NPM Last Update](https://img.shields.io/npm/last-update/eslint-plugin-ore-ui)](https://npmjs.com/package/eslint-plugin-ore-ui)
+[![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/eslint-plugin-ore-ui)](https://npmjs.com/package/eslint-plugin-ore-ui)
+[![GitHub last commit](https://img.shields.io/github/last-commit/8Crafter-Studios/eslint-plugin-ore-ui)](https://github.com/8Crafter-Studios/eslint-plugin-ore-ui/commits/main)
+[![Discord](https://img.shields.io/discord/1213197616570048512?logo=discord&label=discord&link=https%3A%2F%2Fdiscord.8crafter.com)](https://discord.8crafter.com)
+
+An ESLint plugin to be used on Minecraft Bedrock Edition Ore UI scripts.
+
+## Installation
+
+Install ESLint if you haven't already:
+
+```bash
+npm i eslint --save-dev
+```
+
+Install the plugin:
+
+```bash
+npm i eslint-plugin-ore-ui --save-dev
+```
+
+## Usage
+
+### Flat Config
+
+Here are several examples of flat configs using this plugin:
+
+```js
+// 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,
+];
+```
+
+```js
+// 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,
+            },
+        },
+    }
+);
+```
+
+```ts
+// 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,
+            },
+        },
+    }
+);
+```
+
+```cjs
+// 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:
+
+```json
+// .eslintrc.json
+{
+    "extends": [
+        // Enables the plugin and enables the recommended config (without type checking).
+        "plugin:ore-ui/recommended"
+    ]
+}
+```
+
+```json
+// .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
+    }
+}
+```
+
+```json
+// .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
+    }
+}
+```
+
+```cjs
+// .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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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
+
+```ts
+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`
+
+```ts
+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`
+
+```ts
+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`
+
+```ts
+const rules = {
+    "ore-ui/no-illegal-constructors": "off",
+    "ore-ui/no-bugged": "off",
+    "ore-ui/no-critically-bugged": "off",
+};
+```