@simbiat/eslint-plugin-simbiat 1.0.0

package/dist/rules/RequireSuperFirstInConstructor.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @file Rule: simbiat/require-super-first-in-constructor.
+ *
+ * Enforces that the constructor of a Custom Element class:
+ *
+ * 1. Has `super()` as its very first statement.
+ * 2. Calls `super()` with no arguments.
+ *
+ * Per the Custom Elements spec: "A parameter-less call to super() must be the first statement in the constructor body, to establish the correct prototype chain and this value before any further code is run."
+ *
+ * Only applies to classes that directly extend HTMLElement (or configured
+ * base classes). Does not recurse into nested classes.
+ *
+ * Options: baseClasses: string[] – additional class names to treat as HTMLElement. Defaults to ['HTMLElement'].
+ */
+import type { Rule } from 'eslint';
+declare const requireSuperFirstInConstructor: Rule.RuleModule;
+export default requireSuperFirstInConstructor;

package/dist/rules/RequireSuperFirstInConstructor.mjs

@@ -0,0 +1,117 @@
+/**
+ * @file Rule: simbiat/require-super-first-in-constructor.
+ *
+ * Enforces that the constructor of a Custom Element class:
+ *
+ * 1. Has `super()` as its very first statement.
+ * 2. Calls `super()` with no arguments.
+ *
+ * Per the Custom Elements spec: "A parameter-less call to super() must be the first statement in the constructor body, to establish the correct prototype chain and this value before any further code is run."
+ *
+ * Only applies to classes that directly extend HTMLElement (or configured
+ * base classes). Does not recurse into nested classes.
+ *
+ * Options: baseClasses: string[] – additional class names to treat as HTMLElement. Defaults to ['HTMLElement'].
+ */
+import { adaptNodeHandler } from '../utils/Adapters.mjs';
+import { baseClassesSchema } from '../utils/CustomElementsScope.mjs';
+// Helpers
+/**
+ * Returns true if `stmt` is an expression statement containing a bare
+ * `super(…)` call (not `super.method(…)` or any other form).
+ * @param stmt - Statement node to test.
+ * @returns True when the statement is a bare super() call.
+ */
+function isSuperCallStatement(stmt) {
+    return (stmt?.type === 'ExpressionStatement'
+        && stmt.expression?.type === 'CallExpression'
+        && stmt.expression.callee?.type === 'Super');
+}
+// Rule visitor handler
+/**
+ * Checks a MethodDefinition node and reports if super() is not the first
+ * statement or is called with arguments in a Custom Element constructor.
+ * @param context - ESLint rule context for reporting.
+ * @param base_classes - Class names to treat as HTMLElement base classes.
+ * @param node - MethodDefinition node to inspect.
+ */
+function checkMethodDefinition(context, base_classes, node) {
+    const method = node;
+    if (method.kind !== 'constructor') {
+        return;
+    }
+    // node → MethodDefinition, node.parent → ClassBody, node.parent.parent → Class
+    const class_node = method.parent?.parent;
+    if (!class_node) {
+        return;
+    }
+    const super_class = class_node.superClass;
+    if (super_class === null || typeof super_class === 'undefined') {
+        return;
+    }
+    if (super_class.type !== 'Identifier') {
+        return;
+    }
+    if (!base_classes.includes(super_class.name ?? '')) {
+        return;
+    }
+    const body = method.value.body.body;
+    // Check 1: super() must be the first statement.
+    if (!isSuperCallStatement(body[0])) {
+        context.report({
+            node,
+            messageId: 'missingSuperFirst',
+        });
+        return; // no point checking arguments if super() isn't first
+    }
+    // Check 2: super() must have no arguments.
+    const super_call = body[0]?.expression;
+    if ((super_call?.arguments.length ?? 0) > 0) {
+        context.report({
+            node: super_call,
+            messageId: 'superHasArguments',
+        });
+    }
+}
+// Rule visitor handler (top-level, adapted via adaptNodeHandler in `create`)
+/**
+ * Top-level ESLint visitor for MethodDefinition nodes.
+ * @param state - Rule check state containing context and base classes.
+ * @param node - MethodDefinition node from ESLint.
+ */
+function onMethodDefinition(state, node) {
+    checkMethodDefinition(state.context, state.base_classes, node);
+}
+// Rule definition
+const requireSuperFirstInConstructor = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require a parameter-less super() as the first statement in Custom Element constructors.',
+            url: 'https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-conformance',
+        },
+        messages: {
+            missingSuperFirst: 'The first statement in a Custom Element constructor must be a bare super() call.',
+            superHasArguments: 'super() in a Custom Element constructor must be called without arguments.',
+        },
+        schema: baseClassesSchema,
+        hasSuggestions: false,
+    },
+    /**
+     * Creates the rule listeners.
+     * @param context - ESLint rule context.
+     * @returns Rule listener object.
+     */
+    create(context) {
+        const options = context.options[0];
+        const base_classes = options?.baseClasses ?? ['HTMLElement'];
+        const check_state = {
+            context,
+            base_classes,
+        };
+        return {
+            MethodDefinition: adaptNodeHandler(check_state, onMethodDefinition),
+        };
+    },
+};
+export default requireSuperFirstInConstructor;

package/dist/rules/RequireTypeParameter.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @file Rule: simbiat/require-type-parameter.
+ *
+ * Flags `querySelector`, `querySelectorAll`, and `closest` calls in TypeScript
+ * files that lack a type parameter, e.g. `querySelector<HTMLAnchorElement>('.link')`.
+ *
+ * Only activates on .ts / .tsx files; JS files are left alone.
+ * No auto-fix is provided: the correct type depends on the selector and must
+ * be supplied by the developer.
+ */
+import type { Rule } from 'eslint';
+declare const requireTypeParameter: Rule.RuleModule;
+export default requireTypeParameter;

package/dist/rules/RequireTypeParameter.mjs

@@ -0,0 +1,71 @@
+/**
+ * @file Rule: simbiat/require-type-parameter.
+ *
+ * Flags `querySelector`, `querySelectorAll`, and `closest` calls in TypeScript
+ * files that lack a type parameter, e.g. `querySelector<HTMLAnchorElement>('.link')`.
+ *
+ * Only activates on .ts / .tsx files; JS files are left alone.
+ * No auto-fix is provided: the correct type depends on the selector and must
+ * be supplied by the developer.
+ */
+import { adaptNodeHandler } from '../utils/Adapters.mjs';
+/**
+ * Top-level ESLint visitor for CallExpression nodes.
+ * Checks `querySelector`/`querySelectorAll`/`closest` calls for a missing type parameter.
+ * @param context - ESLint rule context.
+ * @param node - CallExpression node from ESLint.
+ */
+function onCallExpression(context, node) {
+    const call = node;
+    if (call.callee.type !== 'MemberExpression') {
+        return;
+    }
+    const { property } = call.callee;
+    if (property.type !== 'Identifier') {
+        return;
+    }
+    if (property.name !== 'querySelector'
+        && property.name !== 'querySelectorAll'
+        && property.name !== 'closest') {
+        return;
+    }
+    // @typescript-eslint/parser attaches type arguments as either
+    // `typeParameters` (older versions) or `typeArguments` (v6+).
+    const has_type_arg = (call.typeParameters?.params.length ?? 0) > 0 || (call.typeArguments?.params.length ?? 0) > 0;
+    if (!has_type_arg) {
+        context.report({
+            node: property,
+            messageId: 'missingTypeParam',
+            data: { method: property.name },
+        });
+    }
+}
+const requireTypeParameter = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require a type parameter on querySelector / querySelectorAll / closest calls in TypeScript files.',
+        },
+        messages: {
+            missingTypeParam: 'Provide a type parameter to {{method}} to be more explicit and reduce casting.',
+        },
+        schema: [],
+        hasSuggestions: false,
+    },
+    /**
+     * Creates the rule listeners.
+     * @param context - ESLint rule context.
+     * @returns Rule listener object.
+     */
+    create(context) {
+        // Limit to TypeScript source files only.
+        const filename = context.filename ?? '';
+        if (!filename.endsWith('.ts') && !filename.endsWith('.tsx')) {
+            return {};
+        }
+        return {
+            CallExpression: adaptNodeHandler(context, onCallExpression),
+        };
+    },
+};
+export default requireTypeParameter;

package/dist/utils/ASTHelpers.d.mts

@@ -0,0 +1,70 @@
+/**
+ * @file AST helper utilities for the prefer-field-initializer and related rules.
+ */
+/**
+ * Collects all declared field names (PropertyDefinition keys) from a class
+ * node's body into a `Set<string>`.
+ * @param class_node - ClassDeclaration or ClassExpression node.
+ * @returns Set of declared field name strings.
+ */
+export declare function collectFieldNames(class_node: unknown): Set<string>;
+/**
+ * Recursively collects all binding names introduced by a parameter or
+ * destructuring pattern node into `out`.
+ * Handles: Identifier, AssignmentPattern, RestElement, ObjectPattern,
+ * ArrayPattern, and TypeScript's TSParameterProperty.
+ * @param param - Parameter or pattern node to collect names from.
+ * @param out - Set to accumulate discovered binding names into.
+ */
+export declare function collectParamNames(param: unknown, out: Set<string>): void;
+/**
+ * Pre-scans a constructor body (BlockStatement) and collects the binding
+ * names of every VariableDeclarator into `out`, without descending into
+ * nested FunctionExpression / FunctionDeclaration / ArrowFunctionExpression
+ * nodes (those have their own scope and are irrelevant here).
+ *
+ * This is called once at constructor-entry time so that later
+ * `this.x = rhs` checks can suppress false positives when `rhs` references
+ * a locally declared variable rather than a constructor parameter.
+ * @param body_node - BlockStatement (the constructor body).
+ * @param out - Set to accumulate discovered local names into.
+ */
+export declare function collectLocalNames(body_node: unknown, out: Set<string>): void;
+/**
+ * Returns true if `node` (or any descendant) is a MemberExpression whose
+ * object is a ThisExpression, e.g. `this.foo`.
+ *
+ * Does NOT recurse into regular FunctionExpression / FunctionDeclaration
+ * because `this` is rebound there. DOES recurse into ArrowFunctionExpression
+ * because arrow functions inherit `this` lexically.
+ * @param node - AST node to inspect.
+ * @returns True if the node or a descendant accesses `this`.
+ */
+export declare function containsThisAccess(node: unknown): boolean;
+/**
+ * Returns true if `node` (or any descendant) contains an Identifier whose
+ * name is in `names`.
+ *
+ * Same `this`-rebinding rules as `containsThisAccess`.
+ * Stops at non-computed property keys in MemberExpression and Property to
+ * avoid false positives on `{ foo: bar }` or `obj.foo` where `foo` is in names.
+ * @param node - AST node to inspect.
+ * @param names - Set of identifier names to search for.
+ * @returns True if the node or a descendant references one of the given names.
+ */
+export declare function containsIdentifierRef(node: unknown, names: Set<string>): boolean;
+/**
+ * Human-readable stringification of a known external-target node.
+ * @param node - AST node representing the target.
+ * @param text - Fallback text when the target cannot be stringified.
+ * @returns Human-readable name for the target node.
+ */
+export declare function targetName(node: unknown, text?: string): string;
+/**
+ * Returns true for nodes that represent a "global" event-listener target:
+ * `document`, `window`, `document.body`, `document.documentElement`,
+ * `document.head`.
+ * @param node - AST node to test.
+ * @returns True when the node is a known external event-listener target.
+ */
+export declare function isExternalTarget(node: unknown): boolean;

package/dist/utils/ASTHelpers.mjs

@@ -0,0 +1,275 @@
+/**
+ * @file AST helper utilities for the prefer-field-initializer and related rules.
+ */
+// Field / parameter name collection
+/**
+ * Collects all declared field names (PropertyDefinition keys) from a class
+ * node's body into a `Set<string>`.
+ * @param class_node - ClassDeclaration or ClassExpression node.
+ * @returns Set of declared field name strings.
+ */
+export function collectFieldNames(class_node) {
+    const node = class_node;
+    const names = new Set();
+    for (const member of node.body?.body ?? []) {
+        if (member.type !== 'PropertyDefinition') {
+            continue;
+        }
+        const key = member.key;
+        let name;
+        if (key?.type === 'Identifier' && typeof key.name === 'string') {
+            name = key.name;
+        }
+        else if (key?.type === 'Literal') {
+            name = String(key.value);
+        }
+        else {
+            name = null;
+        }
+        if (name !== null) {
+            names.add(name);
+        }
+    }
+    return names;
+}
+/**
+ * Recursively collects all binding names introduced by a parameter or
+ * destructuring pattern node into `out`.
+ * Handles: Identifier, AssignmentPattern, RestElement, ObjectPattern,
+ * ArrayPattern, and TypeScript's TSParameterProperty.
+ * @param param - Parameter or pattern node to collect names from.
+ * @param out - Set to accumulate discovered binding names into.
+ */
+export function collectParamNames(param, out) {
+    if (param === null || typeof param === 'undefined' || typeof param !== 'object') {
+        return;
+    }
+    const p = param;
+    switch (p.type) {
+        case 'Identifier':
+            if (typeof p.name === 'string') {
+                out.add(p.name);
+            }
+            break;
+        case 'AssignmentPattern':
+            collectParamNames(p.left, out);
+            break;
+        case 'RestElement':
+            collectParamNames(p.argument, out);
+            break;
+        case 'ObjectPattern':
+            for (const prop of p.properties ?? []) {
+                collectParamNames(prop.type === 'RestElement' ? prop : prop.value, out);
+            }
+            break;
+        case 'ArrayPattern':
+            for (const el of p.elements ?? []) {
+                collectParamNames(el, out); // el may be null for holes
+            }
+            break;
+        case 'TSParameterProperty':
+            // TypeScript: constructor(private foo: string) – foo is both param and field.
+            collectParamNames(p.parameter, out);
+            break;
+        default:
+            break;
+    }
+}
+// AST traversal predicates
+/** Keys that should never be traversed as child AST nodes. */
+const SKIP_KEYS = new Set(['type', 'parent', 'loc', 'range', 'start', 'end']);
+/**
+ * Recursively walks an AST node, collecting variable declarator binding names into `out`,
+ * without descending into nested function boundaries.
+ * @param node - AST node to walk.
+ * @param out - Set to accumulate discovered local variable names into.
+ */
+function walkNode(node, out) {
+    if (node === null || typeof node === 'undefined' || typeof node !== 'object') {
+        return;
+    }
+    const n = node;
+    // Stop at nested-function boundaries – their locals are a different scope.
+    if (n.type === 'FunctionExpression'
+        || n.type === 'FunctionDeclaration'
+        || n.type === 'ArrowFunctionExpression') {
+        return;
+    }
+    if (n.type === 'VariableDeclarator') {
+        // id may be Identifier, ObjectPattern, ArrayPattern, etc.
+        collectParamNames(n.id, out);
+        // Don't walk the init expression – we only care about declared names.
+        return;
+    }
+    for (const key of Object.keys(n)) {
+        if (SKIP_KEYS.has(key)) {
+            continue;
+        }
+        // eslint-disable-next-line security/detect-object-injection
+        const val = n[key];
+        if (Array.isArray(val)) {
+            for (const child of val) {
+                walkNode(child, out);
+            }
+        }
+        else if (val !== null && typeof val === 'object' && typeof val.type === 'string') {
+            walkNode(val, out);
+        }
+    }
+}
+/**
+ * Pre-scans a constructor body (BlockStatement) and collects the binding
+ * names of every VariableDeclarator into `out`, without descending into
+ * nested FunctionExpression / FunctionDeclaration / ArrowFunctionExpression
+ * nodes (those have their own scope and are irrelevant here).
+ *
+ * This is called once at constructor-entry time so that later
+ * `this.x = rhs` checks can suppress false positives when `rhs` references
+ * a locally declared variable rather than a constructor parameter.
+ * @param body_node - BlockStatement (the constructor body).
+ * @param out - Set to accumulate discovered local names into.
+ */
+export function collectLocalNames(body_node, out) {
+    walkNode(body_node, out);
+}
+/**
+ * Returns true if `node` (or any descendant) is a MemberExpression whose
+ * object is a ThisExpression, e.g. `this.foo`.
+ *
+ * Does NOT recurse into regular FunctionExpression / FunctionDeclaration
+ * because `this` is rebound there. DOES recurse into ArrowFunctionExpression
+ * because arrow functions inherit `this` lexically.
+ * @param node - AST node to inspect.
+ * @returns True if the node or a descendant accesses `this`.
+ */
+export function containsThisAccess(node) {
+    if (node === null || typeof node === 'undefined' || typeof node !== 'object') {
+        return false;
+    }
+    const n = node;
+    // `this` is rebound in regular functions – stop recursing.
+    if (n.type === 'FunctionExpression' || n.type === 'FunctionDeclaration') {
+        return false;
+    }
+    if (n.type === 'MemberExpression'
+        && n.object?.type === 'ThisExpression') {
+        return true;
+    }
+    for (const key of Object.keys(n)) {
+        if (SKIP_KEYS.has(key)) {
+            continue;
+        }
+        // eslint-disable-next-line security/detect-object-injection
+        const val = n[key];
+        if (Array.isArray(val)) {
+            for (const child of val) {
+                if (containsThisAccess(child)) {
+                    return true;
+                }
+            }
+        }
+        else if (val !== null
+            && typeof val === 'object'
+            && typeof val.type === 'string'
+            && containsThisAccess(val)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Returns true if `node` (or any descendant) contains an Identifier whose
+ * name is in `names`.
+ *
+ * Same `this`-rebinding rules as `containsThisAccess`.
+ * Stops at non-computed property keys in MemberExpression and Property to
+ * avoid false positives on `{ foo: bar }` or `obj.foo` where `foo` is in names.
+ * @param node - AST node to inspect.
+ * @param names - Set of identifier names to search for.
+ * @returns True if the node or a descendant references one of the given names.
+ */
+export function containsIdentifierRef(node, names) {
+    if (names.size === 0) {
+        return false;
+    }
+    if (node === null || typeof node === 'undefined' || typeof node !== 'object') {
+        return false;
+    }
+    const n = node;
+    if (n.type === 'FunctionExpression' || n.type === 'FunctionDeclaration') {
+        return false;
+    }
+    if (n.type === 'Identifier') {
+        return typeof n.name === 'string' && names.has(n.name);
+    }
+    for (const key of Object.keys(n)) {
+        if (SKIP_KEYS.has(key)) {
+            continue;
+        }
+        // Skip non-computed property keys to avoid treating `{ paramName: val }`
+        // or `obj.paramName` as a reference to the parameter.
+        if ((n.type === 'Property' && key === 'key' && n.computed !== true)
+            || (n.type === 'MemberExpression' && key === 'property' && n.computed !== true)) {
+            continue;
+        }
+        // eslint-disable-next-line security/detect-object-injection
+        const val = n[key];
+        if (Array.isArray(val)) {
+            for (const child of val) {
+                if (containsIdentifierRef(child, names)) {
+                    return true;
+                }
+            }
+        }
+        else if (val !== null
+            && typeof val === 'object'
+            && typeof val.type === 'string'
+            && containsIdentifierRef(val, names)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Human-readable stringification of a known external-target node.
+ * @param node - AST node representing the target.
+ * @param text - Fallback text when the target cannot be stringified.
+ * @returns Human-readable name for the target node.
+ */
+export function targetName(node, text = 'external target') {
+    const n = node;
+    if (n.type === 'Identifier') {
+        return typeof n.name === 'string' ? n.name : text;
+    }
+    if (n.type === 'MemberExpression' && n.computed !== true) {
+        const obj = n.object?.type === 'Identifier' && typeof (n.object).name === 'string'
+            ? String((n.object).name)
+            : '…';
+        const prop = n.property?.type === 'Identifier' && typeof (n.property).name === 'string'
+            ? String((n.property).name)
+            : '…';
+        return `${obj}.${prop}`;
+    }
+    return text;
+}
+/**
+ * Returns true for nodes that represent a "global" event-listener target:
+ * `document`, `window`, `document.body`, `document.documentElement`,
+ * `document.head`.
+ * @param node - AST node to test.
+ * @returns True when the node is a known external event-listener target.
+ */
+export function isExternalTarget(node) {
+    const n = node;
+    if (n.type === 'Identifier') {
+        return n.name === 'document' || n.name === 'window';
+    }
+    if (n.type === 'MemberExpression'
+        && n.computed !== true
+        && n.object?.type === 'Identifier'
+        && (n.object).name === 'document'
+        && n.property?.type === 'Identifier') {
+        return ['body', 'documentElement', 'head'].includes(String((n.property).name));
+    }
+    return false;
+}

package/dist/utils/Adapters.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @file Adapter utilities to wrap stateful handlers into ESLint-compatible visitor callbacks.
+ */
+/**
+ * Wraps a handler that expects (state, node) into the single-argument
+ * signature ESLint passes to visitor callbacks.
+ * @template S - The state type.
+ * @param state - Rule state object to be threaded through.
+ * @param handler - Two-argument handler to wrap.
+ * @returns A single-argument visitor callback suitable for ESLint.
+ */
+export declare function adaptNodeHandler<S>(state: S, handler: (state: S, node: unknown) => void): (node: unknown) => void;
+/**
+ * Wraps a handler that expects only (state) into the no-argument
+ * signature ESLint passes to `:exit` visitor callbacks.
+ * @template S - The state type.
+ * @param state - Rule state object to be threaded through.
+ * @param handler - Single-argument handler to wrap.
+ * @returns A no-argument visitor callback suitable for ESLint.
+ */
+export declare function adaptStateHandler<S>(state: S, handler: (state: S) => void): () => void;

package/dist/utils/Adapters.mjs

@@ -0,0 +1,29 @@
+/**
+ * @file Adapter utilities to wrap stateful handlers into ESLint-compatible visitor callbacks.
+ */
+/**
+ * Wraps a handler that expects (state, node) into the single-argument
+ * signature ESLint passes to visitor callbacks.
+ * @template S - The state type.
+ * @param state - Rule state object to be threaded through.
+ * @param handler - Two-argument handler to wrap.
+ * @returns A single-argument visitor callback suitable for ESLint.
+ */
+export function adaptNodeHandler(state, handler) {
+    return function adaptedNodeHandler(node) {
+        handler(state, node);
+    };
+}
+/**
+ * Wraps a handler that expects only (state) into the no-argument
+ * signature ESLint passes to `:exit` visitor callbacks.
+ * @template S - The state type.
+ * @param state - Rule state object to be threaded through.
+ * @param handler - Single-argument handler to wrap.
+ * @returns A no-argument visitor callback suitable for ESLint.
+ */
+export function adaptStateHandler(state, handler) {
+    return function adaptedStateHandler() {
+        handler(state);
+    };
+}