@simbiat/eslint-plugin-simbiat 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitrii Kustov
+
+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,145 @@
+# eslint-plugin-simbiat
+
+Custom ESLint rules that are used in the [simbiat.eu](https://github.com/Simbiat/simbiat.ru) project. Created with the use of Claude AI (I am realistically not that proficient) but manually reviewed, adjusted, and tested on the existing codebase.
+
+## Installation
+
+```bash
+npm install --save-dev @simbiat/eslint-plugin-simbiat
+```
+
+Requires ESLint
+`>=9.38.0`, [flat config](https://eslint.org/docs/latest/use/configure/configuration-files), and [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c#how-can-i-make-my-typescript-project-output-esm).
+
+---
+
+## Usage (flat config)
+
+```js
+// eslint.config.js
+import simbiat from '@simbiat/eslint-plugin-simbiat';
+
+export default [
+  {
+    plugins: { simbiat },
+    rules: {
+      'simbiat/no-forbidden-in-constructor':          'error',
+      'simbiat/no-external-listeners-in-constructor': 'warn',
+      'simbiat/prefer-field-initializer':             'warn',
+      'simbiat/require-type-parameter':               'warn',
+      'simbiat/require-super-first-in-constructor':   'error', 
+      'simbiat/no-keypress-event':                    'warn',
+    },
+  },
+];
+```
+
+---
+
+## Rules
+
+### `simbiat/no-forbidden-in-constructor` - *problem*
+
+Flags things the [Custom Elements spec](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-conformance)
+forbids in a constructor and in class field definitions:
+
+| Category               | Members                                                                                                                                                                                                                                                                                                                                                                                       |
+|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Attribute manipulation | `this.setAttribute()`, `this.toggleAttribute()`, creation/update attributes like `this.id`, `this.className`, `this.tabIndex`, etc., that are not class fields.                                                                                                                                                                                                                               |
+| Child-element access   | `this.children`, `this.childNodes`, `this.firstChild`, `this.lastChild`, `this.firstElementChild`, `this.lastElementChild`, `this.childElementCount`                                                                                                                                                                                                                                          |
+| Child-element queries  | `this.querySelector()`, `this.querySelectorAll()`, `this.getElementsByTagName()`, `this.getElementsByClassName()`, `this.getElementsByName()`                                                                                                                                                                                                                                                 |
+| Content mutation       | `this.innerHTML`, `this.outerHTML`, `this.textContent`, `this.innerText`, `this.appendChild()`, `this.insertBefore`, `this.replaceChild`, `this.removeChild()`, `this.append()`, `this.prepend()`, `this.replaceChildren()`, `this.insertAdjacentHTML()`, `this.insertAdjacentElement()`, `this.insertAdjacentText()`, `this.after()`, `this.before()`, `this.replaceWith()`, `this.remove()` |
+| Global calls           | `document.write()`, `document.open()`                                                                                                                                                                                                                                                                                                                                                         |
+| Illegal return         | Any `return <expr>;` that is not a bare `return;` or `return this;`                                                                                                                                                                                                                                                                                                                           |
+
+Not flagged: `this.shadowRoot.*`, `this.attachShadow()`, `this.getAttribute()`,
+`this.removeAttribute()`, `appendChild` on shadow-root elements, event
+listeners on shadow-scoped elements.
+
+**Options**
+
+```js
+'simbiat/no-forbidden-in-constructor': ['error', {
+  baseClasses: ['HTMLElement', 'LitElement', 'BaseComponent'],
+}]
+```
+
+`baseClasses` defaults to `['HTMLElement']`.
+
+---
+
+### `simbiat/no-external-listeners-in-constructor` - *suggestion*
+
+Flags `addEventListener` calls on `document`, `window`, `document.body`,
+`document.documentElement`, or `document.head` that appear **directly** in
+the constructor body (not inside a nested callback or arrow function).
+
+These listeners belong in `connectedCallback`, paired with removal in
+`disconnectedCallback`; otherwise they leak when the element is moved or
+re-inserted into the DOM.
+
+**Options** - same `baseClasses` schema as above.
+
+---
+
+### `simbiat/require-super-first-in-constructor` - *problem*
+
+Flags constructors, that do not start with empty
+`super();`. This is normally flagged by TypeScript but may not be flagged in pure JavaScript.
+
+**Options** - same `baseClasses` schema as above.
+
+---
+
+### `simbiat/require-listener-cleanup` - *suggestion*
+
+Verifies that every `addEventListener` call on an external target inside
+`connectedCallback` of an HTMLElement subclass has a matching `removeEventListener` call in `disconnectedCallback`. If the handler in `addEventListener` is a proper class field already, it can be auto-fixed (respective `removeEventListener` will be added).
+
+**Options** - same `baseClasses` schema as above.
+
+---
+
+### `simbiat/prefer-field-initializer` - *suggestion*
+
+Flags `this.x = expr` assignments in a constructor when all the following hold:
+
+1. `x` already has a class field declaration (`PropertyDefinition`).
+2. The RHS does **not** reference a constructor parameter by name.
+3. The RHS does **not** contain `this.anything` (field-initializer vs.
+   constructor-assignment ordering can differ subtly).
+
+Only top-level assignments in the constructor body are checked. Assignments
+inside `if`/`for`/`while` blocks, ternaries, or nested functions are
+intentionally ignored.
+
+> **Known limitation:** references to local variables defined earlier in the
+> constructor (not parameters) are not detected and may produce false
+> positives. Suppress with `// eslint-disable-next-line` where needed.
+
+No auto-fix: the change requires removing the assignment *and* updating the
+field declaration simultaneously.
+
+---
+
+### `simbiat/require-type-parameter` - *suggestion*
+
+Flags `querySelector`, `querySelectorAll` and `closest` calls in TypeScript (`.ts` /
+`.tsx`) files that lack a type parameter.
+
+```ts
+// ✗ flagged
+const element = document.querySelector('.link');
+
+// ✓ OK
+const element = document.querySelector<HTMLAnchorElement>('.link');
+```
+
+JS files are left alone. No auto-fix: the correct type depends on the
+selector and must be supplied by the developer.
+
+---
+
+### `simbiat/no-keypress-event` - *suggestion*
+
+Flags use of `keypress` event, since it is deprecated, and `keydown` is recommended as replacement (or `beforeinput` in some cases). Provides autofix except for `removeEventListener`, because these require a complete match, and if the listener being removed is third party, it will not work as expected. Thus, manual intervention is recommended here.

package/dist/Plugin.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @file Index file for the plugin.
+ */
+declare const Plugin: {
+    meta: {
+        name: string;
+        url: string;
+    };
+    rules: {
+        'no-forbidden-in-constructor': import("eslint").Rule.RuleModule;
+        'no-external-listeners-in-constructor': import("eslint").Rule.RuleModule;
+        'prefer-field-initializer': import("eslint").Rule.RuleModule;
+        'require-type-parameter': import("eslint").Rule.RuleModule;
+        'require-super-first-in-constructor': import("eslint").Rule.RuleModule;
+        'require-listener-cleanup': import("eslint").Rule.RuleModule;
+        'no-keypress-event': import("eslint").Rule.RuleModule;
+    };
+};
+export default Plugin;

package/dist/Plugin.mjs

@@ -0,0 +1,29 @@
+/**
+ * @file Index file for the plugin.
+ */
+// @ts-check
+import noForbiddenInConstructor from './rules/NoForbiddenInConstructor.mjs';
+import noExternalListenersInConstructor from './rules/NoExternalListenersInConstructor.mjs';
+import preferFieldInitializer from './rules/PreferFieldInitializer.mjs';
+import requireListenerCleanup from './rules/RequireListenerCleanup.mjs';
+import requireTypeParameter from './rules/RequireTypeParameter.mjs';
+import requireSuperFirstInConstructor from './rules/RequireSuperFirstInConstructor.mjs';
+import noKeypressEvent from './rules/NoKeypressEvent.mjs';
+const Plugin = {
+    meta: {
+        name: 'eslint-plugin-simbiat',
+        url: 'https://github.com/simbiat/eslint-plugin-simbiat',
+    },
+    rules: {
+        'no-forbidden-in-constructor': noForbiddenInConstructor,
+        'no-external-listeners-in-constructor': noExternalListenersInConstructor,
+        'prefer-field-initializer': preferFieldInitializer,
+        'require-type-parameter': requireTypeParameter,
+        'require-super-first-in-constructor': requireSuperFirstInConstructor,
+        'require-listener-cleanup': requireListenerCleanup,
+        'no-keypress-event': noKeypressEvent,
+    },
+};
+// Used by ESLint Config
+// noinspection JSUnusedGlobalSymbols
+export default Plugin;

package/dist/rules/NoExternalListenersInConstructor.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @file Rule: simbiat/no-external-listeners-in-constructor.
+ *
+ * Flags `addEventListener` calls on `document`, `window`, `document.body`,
+ * `document.documentElement`, or `document.head` that appear *directly* in
+ * the constructor body of a Custom Element (not inside a nested
+ * callback/arrow function).
+ *
+ * These listeners belong in `connectedCallback`, paired with removal in
+ * `disconnectedCallback`; otherwise they leak if the element is moved or
+ * re-inserted into the DOM.
+ *
+ * Options:
+ * baseClasses: string[] – additional class names to treat as HTMLElement. Defaults to ['HTMLElement'].
+ */
+import type { Rule } from 'eslint';
+declare const noExternalListenersInConstructor: Rule.RuleModule;
+export default noExternalListenersInConstructor;

package/dist/rules/NoExternalListenersInConstructor.mjs

@@ -0,0 +1,81 @@
+/**
+ * @file Rule: simbiat/no-external-listeners-in-constructor.
+ *
+ * Flags `addEventListener` calls on `document`, `window`, `document.body`,
+ * `document.documentElement`, or `document.head` that appear *directly* in
+ * the constructor body of a Custom Element (not inside a nested
+ * callback/arrow function).
+ *
+ * These listeners belong in `connectedCallback`, paired with removal in
+ * `disconnectedCallback`; otherwise they leak if the element is moved or
+ * re-inserted into the DOM.
+ *
+ * Options:
+ * baseClasses: string[] – additional class names to treat as HTMLElement. Defaults to ['HTMLElement'].
+ */
+import { adaptNodeHandler } from '../utils/Adapters.mjs';
+import { isExternalTarget, targetName } from '../utils/ASTHelpers.mjs';
+import { isActiveScope, buildScopeVisitors, baseClassesSchema, } from '../utils/CustomElementsScope.mjs';
+// Visitor handler
+/**
+ * Reports `addEventListener` calls on external targets found directly in the constructor.
+ * @param state - Rule state including ESLint context and scope stack.
+ * @param node - CallExpression node to inspect (as unknown from ESLint).
+ */
+function onCallExpression(state, node) {
+    if (!isActiveScope(state)) {
+        return;
+    }
+    const call = node;
+    const { callee } = call;
+    if (callee.type !== 'MemberExpression') {
+        return;
+    }
+    if (callee.property.type !== 'Identifier') {
+        return;
+    }
+    if (callee.property.name !== 'addEventListener') {
+        return;
+    }
+    if (!isExternalTarget(callee.object)) {
+        return;
+    }
+    state.context.report({
+        node: node,
+        messageId: 'externalListener',
+        data: { target: targetName(callee.object) },
+    });
+}
+// Rule definition
+const noExternalListenersInConstructor = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Discourage addEventListener on document / window in Custom Element constructors.',
+        },
+        messages: {
+            externalListener: 'Avoid attaching listeners to {{target}} in the constructor. '
+                + 'Add them in connectedCallback and remove them in disconnectedCallback; '
+                + 'otherwise listeners will be lost if the element is moved or re-inserted.',
+        },
+        schema: baseClassesSchema,
+        hasSuggestions: false,
+    },
+    /**
+     * Create rule.
+     * @param context - Contect to process.
+     */
+    create(context) {
+        const options = context.options[0];
+        const state = {
+            context,
+            stack: [],
+            base_classes: options?.baseClasses ?? ['HTMLElement'],
+        };
+        return {
+            ...buildScopeVisitors(state),
+            CallExpression: adaptNodeHandler(state, onCallExpression),
+        };
+    },
+};
+export default noExternalListenersInConstructor;

package/dist/rules/NoForbiddenInConstructor.d.mts

@@ -0,0 +1,28 @@
+/**
+ * @file Rule: simbiat/no-forbidden-in-constructor.
+ *
+ * Flags everything the Custom Elements spec says you cannot or should not do
+ * during the construction phase — both in the constructor body and in instance
+ * field initializers (which run as part of construction, before the element
+ * is connected).
+ *
+ * Attribute / property writes: any `this.x = value` assignment where `x` is not declared as a class field (PropertyDefinition) in the current class body is flagged.
+ *
+ * DOMTokenList mutation: this.classList.add / remove / toggle / replace (…), this.part.add / remove / toggle / replace (…)
+ *
+ * Chained attribute / style writes: this.dataset.<key> = value / this.style.<prop> = value
+ *
+ * Method-based attribute manipulation: this.setAttribute(…) / this.toggleAttribute(…)
+ *
+ * Child / content access (reads and mutations via children-related properties
+ * and methods such as querySelector, appendChild, innerHTML, etc.)
+ *
+ * Forbidden global calls: document.write(…) / document.open(…)
+ *
+ * Illegal return (constructor only): any `return <expr>` that is not a bare `return` or `return this`.
+ *
+ * Options: baseClasses: string[] – additional class names to treat as HTMLElement. Defaults to ['HTMLElement'].
+ */
+import type { Rule } from 'eslint';
+declare const noForbiddenInConstructor: Rule.RuleModule;
+export default noForbiddenInConstructor;