@blumintinc/eslint-plugin-blumint 1.12.6 → 1.14.0

package/lib/rules/prefer-params-over-parent-id.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * @fileoverview Enforce the use of event.params over .ref.parent.id in Firebase change handlers
+ * @author BluMint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferParamsOverParentId = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const HANDLER_TYPES = new Set([
+    'DocumentChangeHandler',
+    'DocumentChangeHandlerTransaction',
+    'RealtimeDbChangeHandler',
+    'RealtimeDbChangeHandlerTransaction',
+]);
+const getQualifiedNameIdentifier = (typeName) => {
+    if (typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return typeName.name;
+    }
+    if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName &&
+        typeName.right.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return typeName.right.name;
+    }
+    return null;
+};
+const checkTypeAnnotationForHandler = (typeNode) => {
+    switch (typeNode.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeReference: {
+            const typeIdentifier = getQualifiedNameIdentifier(typeNode.typeName);
+            return typeIdentifier ? HANDLER_TYPES.has(typeIdentifier) : false;
+        }
+        case utils_1.AST_NODE_TYPES.TSUnionType:
+            return typeNode.types.some(checkTypeAnnotationForHandler);
+        case utils_1.AST_NODE_TYPES.TSIntersectionType:
+            return typeNode.types.some(checkTypeAnnotationForHandler);
+        default:
+            return false;
+    }
+};
+const findTypeAnnotationInContext = (node) => {
+    if (node.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        node.parent.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.parent.id.typeAnnotation) {
+        return node.parent.id.typeAnnotation;
+    }
+    if (node.parent?.type === utils_1.AST_NODE_TYPES.AssignmentExpression &&
+        node.parent.left.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.parent.left.typeAnnotation) {
+        return node.parent.left.typeAnnotation;
+    }
+    if (node.parent?.type === utils_1.AST_NODE_TYPES.Property &&
+        node.parent.value === node) {
+        let current = node.parent.parent;
+        while (current) {
+            if (current.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                current.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                current.id.typeAnnotation) {
+                return current.id.typeAnnotation;
+            }
+            current = current.parent;
+        }
+    }
+    return undefined;
+};
+const isFirebaseChangeHandler = (node) => {
+    if (node.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+        node.type !== utils_1.AST_NODE_TYPES.FunctionExpression &&
+        node.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+        return false;
+    }
+    const typeAnnotation = findTypeAnnotationInContext(node);
+    if (!typeAnnotation) {
+        return false;
+    }
+    return checkTypeAnnotationForHandler(typeAnnotation.typeAnnotation);
+};
+const isParentIdAccess = (node) => {
+    if (node.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+        node.property.name !== 'id') {
+        return { isMatch: false, depth: 0 };
+    }
+    const chain = [];
+    let current = node.object;
+    while (current && current.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        if (current.property.type !== utils_1.AST_NODE_TYPES.Identifier) {
+            return { isMatch: false, depth: 0 };
+        }
+        chain.unshift(current.property.name);
+        current = current.object;
+    }
+    if (chain.length < 2) {
+        return { isMatch: false, depth: 0 };
+    }
+    const refIndex = chain.lastIndexOf('ref');
+    if (refIndex === -1) {
+        return { isMatch: false, depth: 0 };
+    }
+    const parentSegment = chain.slice(refIndex + 1);
+    if (parentSegment.length === 0) {
+        return { isMatch: false, depth: 0 };
+    }
+    const invalidParent = parentSegment.some((segment) => segment !== 'parent');
+    if (invalidParent) {
+        return { isMatch: false, depth: 0 };
+    }
+    const depth = parentSegment.length;
+    return { isMatch: depth > 0, depth };
+};
+const getParentParamName = (depth) => {
+    if (depth === 1) {
+        return 'userId';
+    }
+    if (depth === 2) {
+        return 'parentId';
+    }
+    return `parent${depth}Id`;
+};
+const findHandlerFunction = (node, handlerNodes) => {
+    let current = node;
+    while (current) {
+        if (handlerNodes.has(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+};
+const hasOptionalChaining = (node) => {
+    let current = node;
+    while (current && current.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        if (current.optional) {
+            return true;
+        }
+        current = current.object;
+    }
+    return false;
+};
+const findParamsInPattern = (pattern) => {
+    for (const prop of pattern.properties) {
+        if (prop.type === utils_1.AST_NODE_TYPES.Property &&
+            prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+            prop.key.name === 'params') {
+            if (prop.value.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return { identifier: prop.value.name };
+            }
+            if (prop.value.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
+                const properties = new Map();
+                for (const p of prop.value.properties) {
+                    if (p.type === utils_1.AST_NODE_TYPES.Property &&
+                        p.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        p.value.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        properties.set(p.key.name, p.value.name);
+                    }
+                }
+                return { properties };
+            }
+        }
+    }
+    return null;
+};
+const getParamsInScope = (handlerNode) => {
+    if (handlerNode.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+        handlerNode.type !== utils_1.AST_NODE_TYPES.FunctionExpression &&
+        handlerNode.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+        return null;
+    }
+    const firstParam = handlerNode.params[0];
+    if (!firstParam) {
+        return null;
+    }
+    if (firstParam.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
+        const paramsInScope = findParamsInPattern(firstParam);
+        if (paramsInScope) {
+            return paramsInScope;
+        }
+    }
+    if (handlerNode.body &&
+        handlerNode.body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+        const eventParamName = firstParam.type === utils_1.AST_NODE_TYPES.Identifier ? firstParam.name : 'event';
+        for (const statement of handlerNode.body.body) {
+            if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
+                continue;
+            }
+            for (const declarator of statement.declarations) {
+                if (declarator.id.type !== utils_1.AST_NODE_TYPES.ObjectPattern ||
+                    !declarator.init ||
+                    declarator.init.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                    declarator.init.name !== eventParamName) {
+                    continue;
+                }
+                const paramsInScope = findParamsInPattern(declarator.id);
+                if (paramsInScope) {
+                    return paramsInScope;
+                }
+            }
+        }
+    }
+    return null;
+};
+exports.preferParamsOverParentId = (0, createRule_1.createRule)({
+    name: 'prefer-params-over-parent-id',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer handler params for parent IDs instead of traversing ref.parent.id so Firebase triggers stay aligned with path templates and type-safe.',
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [],
+        messages: {
+            preferParams: [
+                "What's wrong: This code reads an ID via `ref.parent...id` instead of using the trigger's params.",
+                '',
+                'Why it matters: Walking `ref.parent` ties the handler to the current path depth; when collections change, it can yield the wrong ID (or a collection name) and bypasses the typed params the trigger provides.',
+                '',
+                'How to fix: Read the ID from `params.{{paramName}}` (or destructure `const { params } = event` and then access `params.{{paramName}}`).',
+            ].join('\n'),
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const handlerNodes = new Set();
+        return {
+            // Track Firebase change handler functions
+            'FunctionDeclaration, FunctionExpression, ArrowFunctionExpression'(node) {
+                if (isFirebaseChangeHandler(node)) {
+                    handlerNodes.add(node);
+                }
+            },
+            // Detect .ref.parent.id patterns
+            MemberExpression(node) {
+                const parentAccess = isParentIdAccess(node);
+                if (parentAccess.isMatch) {
+                    const handlerNode = findHandlerFunction(node, handlerNodes);
+                    if (handlerNode) {
+                        const hasOptional = hasOptionalChaining(node);
+                        const paramsInScope = getParamsInScope(handlerNode);
+                        if (!paramsInScope) {
+                            context.report({
+                                node,
+                                messageId: 'preferParams',
+                                data: {
+                                    paramName: getParentParamName(parentAccess.depth),
+                                },
+                            });
+                            return;
+                        }
+                        const paramSuggestion = getParentParamName(parentAccess.depth);
+                        let replacement = null;
+                        if (paramsInScope.identifier) {
+                            replacement = hasOptional
+                                ? `${paramsInScope.identifier}?.${paramSuggestion}`
+                                : `${paramsInScope.identifier}.${paramSuggestion}`;
+                        }
+                        else if (paramsInScope.properties) {
+                            const localName = paramsInScope.properties.get(paramSuggestion);
+                            if (localName) {
+                                replacement = localName;
+                            }
+                        }
+                        context.report({
+                            node,
+                            messageId: 'preferParams',
+                            data: {
+                                paramName: paramSuggestion,
+                            },
+                            fix: replacement
+                                ? (fixer) => fixer.replaceText(node, replacement)
+                                : undefined,
+                        });
+                    }
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=prefer-params-over-parent-id.js.map

package/lib/rules/prefer-settings-object.js

@@ -40,8 +40,8 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
             },
         ],
         messages: {
-            tooManyParams: 'Function has too many parameters ({{count}}). Use a settings object instead.',
-            sameTypeParams: 'Function has multiple parameters of the same type. Use a settings object instead.',
+            tooManyParams: "Function accepts {{count}} positional parameters (limit {{minimum}}). Long positional lists hide each argument's meaning and make call sites easy to mis-order. Pass a single settings object so callers name each field and keep the call readable.",
+            sameTypeParams: 'Function receives {{paramCount}} positional parameters including multiple "{{type}}" values. Repeated types in positional arguments invite swapped values and force callers to remember parameter order. Replace the positional list with a settings object so each value is labeled and self-documenting.',
         },
     },
     defaultOptions: [defaultOptions],
@@ -60,10 +60,12 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                         ? typeNode.typeName.name
                         : 'unknown';
                     // If there are type parameters, include them in the type signature
-                    if (typeNode.typeParameters && typeNode.typeParameters.params.length > 0) {
+                    if (typeNode.typeParameters &&
+                        typeNode.typeParameters.params.length > 0) {
+                        const sourceCode = context.sourceCode;
                         const typeParams = typeNode.typeParameters.params
-                            .map(param => param.type)
-                            .join('_');
+                            .map((param) => sourceCode.getText(param))
+                            .join(', ');
                         return `${typeName}<${typeParams}>`;
                     }
                     return typeName;
@@ -78,10 +80,12 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                         ? typeNode.typeName.name
                         : 'unknown';
                     // If there are type parameters, include them in the type signature
-                    if (typeNode.typeParameters && typeNode.typeParameters.params.length > 0) {
+                    if (typeNode.typeParameters &&
+                        typeNode.typeParameters.params.length > 0) {
+                        const sourceCode = context.sourceCode;
                         const typeParams = typeNode.typeParameters.params
-                            .map(param => param.type)
-                            .join('_');
+                            .map((param) => sourceCode.getText(param))
+                            .join(', ');
                         return `${typeName}<${typeParams}>`;
                     }
                     return typeName;
@@ -96,17 +100,17 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
             }
             return 'unknown';
         }
-        function hasSameTypeParameters(params) {
+        function findDuplicateParameterType(params) {
             const typeMap = new Map();
             for (const param of params) {
                 const type = getParameterType(param);
                 const count = (typeMap.get(type) || 0) + 1;
                 typeMap.set(type, count);
                 if (count > 1) {
-                    return true;
+                    return type;
                 }
             }
-            return false;
+            return null;
         }
         function isBuiltInOrThirdParty(node) {
             // Check if the node is part of a new expression (constructor call)
@@ -287,8 +291,10 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                 // Check if the function name or its type annotation suggests it's a handler with transaction
                 if (functionName.includes('Transaction') ||
                     functionName.includes('WithTransaction') ||
-                    (node.parent.id.typeAnnotation?.typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
-                        node.parent.id.typeAnnotation.typeAnnotation.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    (node.parent.id.typeAnnotation?.typeAnnotation.type ===
+                        utils_1.AST_NODE_TYPES.TSTypeReference &&
+                        node.parent.id.typeAnnotation.typeAnnotation.typeName.type ===
+                            utils_1.AST_NODE_TYPES.Identifier &&
                         (node.parent.id.typeAnnotation.typeAnnotation.typeName.name.includes('Transaction') ||
                             node.parent.id.typeAnnotation.typeAnnotation.typeName.name.includes('WithTransaction')))) {
                     return true;
@@ -306,16 +312,18 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                 context.report({
                     node,
                     messageId: 'tooManyParams',
-                    data: { count: params.length },
+                    data: { count: params.length, minimum: minParams },
                 });
                 return;
             }
             // Then check for same type parameters if enabled
             if (finalOptions.checkSameTypeParameters && params.length >= 2) {
-                if (hasSameTypeParameters(params)) {
+                const duplicateType = findDuplicateParameterType(params);
+                if (duplicateType) {
                     context.report({
                         node,
                         messageId: 'sameTypeParams',
+                        data: { type: duplicateType, paramCount: params.length },
                     });
                 }
             }

package/lib/rules/prefer-type-alias-over-typeof-constant.d.ts

@@ -0,0 +1,3 @@
+import { TSESLint } from '@typescript-eslint/utils';
+export type MessageIds = 'preferTypeAlias' | 'defineTypeBeforeConstant';
+export declare const preferTypeAliasOverTypeofConstant: TSESLint.RuleModule<MessageIds, never[]>;

package/lib/rules/prefer-type-alias-over-typeof-constant.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferTypeAliasOverTypeofConstant = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const PAREN_TYPE = utils_1.AST_NODE_TYPES.TSParenthesizedType ??
+    'TSParenthesizedType';
+const isParenthesizedType = (node) => {
+    return node.type === PAREN_TYPE;
+};
+/** Utility to convert CONSTANT_CASE or snake/kebab to PascalCase */
+function toPascalCase(name) {
+    return name
+        .split(/[_-]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('');
+}
+/** Determine if a value initializer represents a function or class (which we should ignore). */
+function isFunctionOrClassInitializer(init) {
+    if (!init)
+        return false;
+    return (init.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        init.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        init.type === utils_1.AST_NODE_TYPES.ClassExpression);
+}
+/** Determine if node is a simple constant literal or object/array literal possibly with `as const` */
+function isConstantLikeInitializer(init) {
+    if (!init)
+        return false;
+    if (isFunctionOrClassInitializer(init))
+        return false;
+    switch (init.type) {
+        case utils_1.AST_NODE_TYPES.Literal:
+            return true;
+        case utils_1.AST_NODE_TYPES.TemplateLiteral:
+            return init.expressions.length === 0;
+        case utils_1.AST_NODE_TYPES.ObjectExpression:
+            return true;
+        case utils_1.AST_NODE_TYPES.ArrayExpression:
+            return true;
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+            return isConstantLikeInitializer(init.expression);
+        case utils_1.AST_NODE_TYPES.UnaryExpression: {
+            // treat unary constants (e.g., -1) as constant-like; exclude typeof
+            if (init.operator === 'typeof')
+                return false;
+            return isConstantLikeInitializer(init.argument);
+        }
+        default:
+            return false;
+    }
+}
+/** Traverse a TSType and collect referenced identifier names (e.g., A, B in A | B). */
+function collectReferencedTypeNames(node, acc = new Set()) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeReference: {
+            if (node.typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+                acc.add(node.typeName.name);
+            }
+            if (node.typeParameters) {
+                for (const p of node.typeParameters.params)
+                    collectReferencedTypeNames(p, acc);
+            }
+            break;
+        }
+        case utils_1.AST_NODE_TYPES.TSUnionType:
+        case utils_1.AST_NODE_TYPES.TSIntersectionType: {
+            for (const t of node.types)
+                collectReferencedTypeNames(t, acc);
+            break;
+        }
+        case utils_1.AST_NODE_TYPES.TSArrayType: {
+            const arr = node;
+            collectReferencedTypeNames(arr.elementType, acc);
+            break;
+        }
+        case utils_1.AST_NODE_TYPES.TSTypeOperator: {
+            const op = node;
+            if (op.typeAnnotation)
+                collectReferencedTypeNames(op.typeAnnotation, acc);
+            break;
+        }
+        case utils_1.AST_NODE_TYPES.TSTupleType: {
+            const tup = node;
+            for (const e of tup.elementTypes)
+                collectReferencedTypeNames(e, acc);
+            break;
+        }
+        default: {
+            if (isParenthesizedType(node)) {
+                collectReferencedTypeNames(node.typeAnnotation, acc);
+            }
+            break;
+        }
+    }
+    return acc;
+}
+/** Collects module-level consts and type aliases for quick lookup */
+function collectTopLevelContext(program) {
+    const topLevelConstInitByName = new Map();
+    const topLevelConstNodeByName = new Map();
+    const typeAliasByName = new Map();
+    const importedValueNames = new Set();
+    const importedTypeNames = new Set();
+    for (const stmt of program.body) {
+        if (stmt.type === utils_1.AST_NODE_TYPES.ImportDeclaration) {
+            const isTypeImport = stmt.importKind === 'type';
+            for (const spec of stmt.specifiers) {
+                // import type { Foo } from '...'
+                // import { Foo } from '...' as value import
+                if (spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                    if (isTypeImport || spec.importKind === 'type') {
+                        importedTypeNames.add(spec.local.name);
+                    }
+                    else {
+                        importedValueNames.add(spec.local.name);
+                    }
+                }
+                else if (spec.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier) {
+                    if (isTypeImport) {
+                        importedTypeNames.add(spec.local.name);
+                    }
+                    else {
+                        importedValueNames.add(spec.local.name);
+                    }
+                }
+                else if (spec.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+                    // Namespace imports expose names via MemberExpression; not tracked individually
+                }
+            }
+        }
+        else if (stmt.type === utils_1.AST_NODE_TYPES.VariableDeclaration &&
+            stmt.kind === 'const') {
+            for (const decl of stmt.declarations) {
+                if (decl.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    topLevelConstInitByName.set(decl.id.name, decl.init ?? null);
+                    topLevelConstNodeByName.set(decl.id.name, decl);
+                }
+            }
+        }
+        else if (stmt.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+            typeAliasByName.set(stmt.id.name, stmt);
+        }
+        else if (stmt.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+            stmt.declaration) {
+            // Handle exported declarations: export const FOO = ...; export type Foo = ...
+            const decl = stmt.declaration;
+            if (decl.type === utils_1.AST_NODE_TYPES.VariableDeclaration &&
+                decl.kind === 'const') {
+                for (const d of decl.declarations) {
+                    if (d.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        topLevelConstInitByName.set(d.id.name, d.init ?? null);
+                        topLevelConstNodeByName.set(d.id.name, d);
+                    }
+                }
+            }
+            else if (decl.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+                typeAliasByName.set(decl.id.name, decl);
+            }
+        }
+    }
+    return {
+        topLevelConstInitByName,
+        topLevelConstNodeByName,
+        typeAliasByName,
+        importedValueNames,
+        importedTypeNames,
+    };
+}
+exports.preferTypeAliasOverTypeofConstant = (0, createRule_1.createRule)({
+    name: 'prefer-type-alias-over-typeof-constant',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer named type aliases over `typeof` on same-file global constants; ensure types are declared before constants.',
+            recommended: 'error',
+        },
+        hasSuggestions: false,
+        schema: [],
+        messages: {
+            preferTypeAlias: 'Type derived from same-file constant "{{constName}}" couples the type to its runtime value and scatters literal unions across the file. Create a named alias such as "{{suggested}}" and reference that alias instead of `typeof {{constName}}` so the type stays stable even if the value changes.',
+            defineTypeBeforeConstant: 'Type alias "{{typeName}}" appears after constant "{{constName}}", which hides the shape from readers and risks using an undeclared alias. Declare "{{typeName}}" before "{{constName}}" so the type is visible where it is consumed and can be reused consistently.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        let collected;
+        return {
+            Program(program) {
+                collected = collectTopLevelContext(program);
+            },
+            // Enforce that type aliases referenced by const annotations appear before the const
+            VariableDeclarator(node) {
+                if (!collected)
+                    return;
+                if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier)
+                    return;
+                const constName = node.id.name;
+                // Only for top-level consts
+                const decl = collected.topLevelConstNodeByName.get(constName);
+                if (!decl || decl !== node)
+                    return;
+                const parentDecl = node.parent;
+                if (!parentDecl || parentDecl.kind !== 'const')
+                    return;
+                const typeAnn = node.id.typeAnnotation?.typeAnnotation;
+                if (!typeAnn)
+                    return;
+                for (const typeName of collectReferencedTypeNames(typeAnn)) {
+                    // If imported type, allow any order
+                    if (collected.importedTypeNames.has(typeName))
+                        continue;
+                    const typeDecl = collected.typeAliasByName.get(typeName);
+                    if (typeDecl && typeDecl.range[0] > parentDecl.range[0]) {
+                        context.report({
+                            node: node.id,
+                            messageId: 'defineTypeBeforeConstant',
+                            data: { typeName, constName },
+                        });
+                    }
+                }
+            },
+            // Core rule: flag `typeof CONST` when CONST is a same-file top-level const and constant-like
+            TSTypeQuery(node) {
+                if (!collected)
+                    return;
+                // Skip `keyof typeof X`
+                if (node.parent &&
+                    node.parent.type === utils_1.AST_NODE_TYPES.TSTypeOperator &&
+                    node.parent.operator === 'keyof') {
+                    return;
+                }
+                if (node.exprName.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    return;
+                }
+                const name = node.exprName.name;
+                // Imported values: do not enforce (may suggest in future)
+                if (collected.importedValueNames.has(name)) {
+                    return;
+                }
+                const init = collected.topLevelConstInitByName.get(name);
+                if (init === undefined) {
+                    // Not a top-level const in this file
+                    return;
+                }
+                if (!isConstantLikeInitializer(init)) {
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'preferTypeAlias',
+                    data: { constName: name, suggested: toPascalCase(name) },
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=prefer-type-alias-over-typeof-constant.js.map

package/lib/rules/prefer-type-over-interface.js

@@ -12,7 +12,9 @@ exports.preferTypeOverInterface = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            preferType: 'Prefer using type alias over interface.',
+            preferType: 'Interface "{{interfaceName}}" should be declared as a type alias. ' +
+                'Interfaces can merge across declarations and extend in chains, which fragments the resulting shape across files and makes composition harder to predict and trace. ' +
+                'Replace `interface` with `type` and use intersections (for example, `type {{interfaceName}} = Base & { field: string }`) to keep the contract closed and predictable.',
         },
         fixable: 'code',
     },
@@ -23,8 +25,11 @@ exports.preferTypeOverInterface = (0, createRule_1.createRule)({
                 context.report({
                     node,
                     messageId: 'preferType',
+                    data: {
+                        interfaceName: node.id.name,
+                    },
                     fix(fixer) {
-                        const sourceCode = context.getSourceCode();
+                        const sourceCode = context.sourceCode;
                         const openingBrace = sourceCode.getTokenAfter(node.id, {
                             filter: (token) => token.value === '{',
                         });

package/lib/rules/prefer-url-tostring-over-tojson.d.ts

@@ -0,0 +1,2 @@
+import { TSESLint } from '@typescript-eslint/utils';
+export declare const preferUrlToStringOverToJson: TSESLint.RuleModule<'preferToString', never[]>;