@blumintinc/eslint-plugin-blumint 1.13.0 → 1.14.0

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

@@ -13,6 +13,190 @@ const HANDLER_TYPES = new Set([
     '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: {
@@ -24,199 +208,64 @@ exports.preferParamsOverParentId = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            preferParams: 'Accessing parent IDs through `ref.parent.id` bypasses the handler params and breaks when collection nesting changes. Use the params object for stable, typed IDs instead (destructure `const { params: { {{paramName}} } } = event` or read `params.{{paramName}}`).',
+            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) {
-        // Track functions that are Firebase change handlers
-        const handlerFunctions = new Set();
-        function findTypeAnnotationInContext(node) {
-            // Check variable declarator type annotation
-            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;
-            }
-            // Check assignment expression with type annotation
-            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;
-            }
-            // Check property definition type annotation
-            if (node.parent?.type === utils_1.AST_NODE_TYPES.Property &&
-                node.parent.value === node) {
-                // Look up the tree for type annotation
-                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;
-        }
-        function 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);
-        }
-        function checkTypeAnnotationForHandler(typeNode) {
-            if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
-                typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
-                return HANDLER_TYPES.has(typeNode.typeName.name);
-            }
-            return false;
-        }
-        function isParentIdAccess(node) {
-            // Check if this is a .ref.parent[.parent...].id pattern
-            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.indexOf('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 };
-        }
-        function findHandlerFunction(node) {
-            let current = node;
-            while (current) {
-                if (handlerFunctions.has(current)) {
-                    return current;
-                }
-                current = current.parent;
-            }
-            return null;
-        }
-        function 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;
-        }
-        function isParamsInScope(handlerNode) {
-            // Check if params is destructured from the event parameter
-            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) {
-                const firstParam = handlerNode.params[0];
-                if (!firstParam)
-                    return false;
-                // Check for destructuring pattern: ({ params }) or ({ data, params })
-                if (firstParam.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
-                    return firstParam.properties.some((prop) => {
-                        if (prop.type === utils_1.AST_NODE_TYPES.Property &&
-                            prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
-                            prop.key.name === 'params') {
-                            return true;
-                        }
-                        return false;
-                    });
-                }
-                // Check for variable declarations inside the function that destructure params
-                if (handlerNode.body &&
-                    handlerNode.body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
-                    for (const statement of handlerNode.body.body) {
-                        if (statement.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
-                            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) {
-                                    // Check if destructuring from event parameter
-                                    const eventParamName = firstParam.type === utils_1.AST_NODE_TYPES.Identifier
-                                        ? firstParam.name
-                                        : 'event';
-                                    if (declarator.init.name === eventParamName) {
-                                        return declarator.id.properties.some((prop) => {
-                                            if (prop.type === utils_1.AST_NODE_TYPES.Property &&
-                                                prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                                prop.key.name === 'params') {
-                                                return true;
-                                            }
-                                            return false;
-                                        });
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-            return false;
-        }
+        const handlerNodes = new Set();
         return {
             // Track Firebase change handler functions
             'FunctionDeclaration, FunctionExpression, ArrowFunctionExpression'(node) {
                 if (isFirebaseChangeHandler(node)) {
-                    handlerFunctions.add(node);
+                    handlerNodes.add(node);
                 }
             },
             // Detect .ref.parent.id patterns
             MemberExpression(node) {
                 const parentAccess = isParentIdAccess(node);
                 if (parentAccess.isMatch) {
-                    const handlerNode = findHandlerFunction(node);
+                    const handlerNode = findHandlerFunction(node, handlerNodes);
                     if (handlerNode) {
                         const hasOptional = hasOptionalChaining(node);
-                        const paramsInScope = isParamsInScope(handlerNode);
-                        // Suggest different parameter names based on depth
-                        // Note: These conventions may vary by data model; adjust if needed
-                        const paramSuggestion = parentAccess.depth === 1
-                            ? 'userId'
-                            : parentAccess.depth === 2
-                                ? 'parentId'
-                                : `parent${parentAccess.depth}Id`;
+                        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: paramsInScope
-                                ? (fixer) => {
-                                    const replacement = hasOptional
-                                        ? `params?.${paramSuggestion}`
-                                        : `params.${paramSuggestion}`;
-                                    return fixer.replaceText(node, replacement);
-                                }
+                            fix: replacement
+                                ? (fixer) => fixer.replaceText(node, replacement)
                                 : undefined,
                         });
                     }

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

@@ -62,7 +62,7 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                     // If there are type parameters, include them in the type signature
                     if (typeNode.typeParameters &&
                         typeNode.typeParameters.params.length > 0) {
-                        const sourceCode = context.getSourceCode();
+                        const sourceCode = context.sourceCode;
                         const typeParams = typeNode.typeParameters.params
                             .map((param) => sourceCode.getText(param))
                             .join(', ');
@@ -82,7 +82,7 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                     // If there are type parameters, include them in the type signature
                     if (typeNode.typeParameters &&
                         typeNode.typeParameters.params.length > 0) {
-                        const sourceCode = context.getSourceCode();
+                        const sourceCode = context.sourceCode;
                         const typeParams = typeNode.typeParameters.params
                             .map((param) => sourceCode.getText(param))
                             .join(', ');

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.js

@@ -50,7 +50,7 @@ function isOptionalMemberExpression(expr) {
 }
 exports.preferUrlToStringOverToJson = (0, createRule_1.createRule)({
     create(context) {
-        const sourceCode = context.getSourceCode();
+        const sourceCode = context.sourceCode;
         const parserServices = sourceCode.parserServices;
         const urlIdentifierNames = new Set();
         let checker = null;
@@ -132,6 +132,9 @@ exports.preferUrlToStringOverToJson = (0, createRule_1.createRule)({
                 context.report({
                     node,
                     messageId: 'preferToString',
+                    data: {
+                        urlText: sourceCode.getText(objectExpr),
+                    },
                     fix(fixer) {
                         // If inside JSON.stringify and not optional chain, replace the entire call with just the object
                         if (insideJSONStringify &&
@@ -151,14 +154,14 @@ exports.preferUrlToStringOverToJson = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce the use of toString() over toJSON() on URL objects. Prefer passing URL objects directly to JSON.stringify, which will call toJSON automatically. See docs/rules/prefer-url-tostring-over-tojson.md for examples.',
+            description: 'Enforce the use of toString() over toJSON() on URL objects.',
             recommended: 'error',
             requiresTypeChecking: false,
         },
         fixable: 'code',
         schema: [],
         messages: {
-            preferToString: 'Use toString() instead of toJSON() on URL objects. When serializing with JSON.stringify, pass the URL object directly.',
+            preferToString: 'URL value {{urlText}} calls toJSON() explicitly. URL.toJSON() delegates directly to toString(), so the call is redundant. Inside JSON.stringify it is unnecessary because JSON.stringify already invokes toJSON automatically; elsewhere it hides intent because readers must remember the delegation to see it produces the same string as toString. Use toString() when you need an explicit string, or pass the URL directly to JSON.stringify to rely on its built-in serialization.',
         },
     },
     defaultOptions: [],

package/lib/rules/prefer-use-deep-compare-memo.js

@@ -106,7 +106,7 @@ function isNonPrimitiveWithTypes(context, expr) {
 }
 function collectMemoizedIdentifiers(context) {
     const memoized = new Set();
-    const sourceCode = context.getSourceCode();
+    const sourceCode = context.sourceCode;
     const program = sourceCode.ast;
     function visit(node) {
         if (node.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
@@ -156,7 +156,7 @@ function collectMemoizedIdentifiers(context) {
 }
 function ensureDeepCompareImportFixes(context, fixer) {
     const fixes = [];
-    const sourceCode = context.getSourceCode();
+    const sourceCode = context.sourceCode;
     const program = sourceCode.ast;
     // If already imported anywhere, skip adding
     const hasImport = program.body.some((n) => n.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
@@ -227,7 +227,7 @@ function removeImportSpecifierFixes(sourceCode, fixer, importDecl, specifier) {
     return fixes;
 }
 function isImportedIdentifier(context, name) {
-    const sourceCode = context.getSourceCode();
+    const sourceCode = context.sourceCode;
     const program = sourceCode.ast;
     for (const node of program.body) {
         if (node.type === utils_1.AST_NODE_TYPES.ImportDeclaration) {
@@ -319,7 +319,7 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            preferUseDeepCompareMemo: 'Use useDeepCompareMemo instead of useMemo because dependency array contains unmemoized non-primitive values.',
+            preferUseDeepCompareMemo: 'Dependency array for "{{hook}}" includes objects/arrays/functions that change identity each render, so React treats them as changed and reruns the memoized computation, triggering avoidable renders. Use useDeepCompareMemo (or memoize those dependencies first) so comparisons use deep equality and the memo stays stable.',
         },
     },
     defaultOptions: [],
@@ -386,6 +386,9 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
                 context.report({
                     node,
                     messageId: 'preferUseDeepCompareMemo',
+                    data: {
+                        hook: 'useMemo',
+                    },
                     fix(fixer) {
                         const fixes = [];
                         // Replace callee
@@ -398,7 +401,7 @@ exports.preferUseDeepCompareMemo = (0, createRule_1.createRule)({
                         // Ensure import exists
                         fixes.push(...ensureDeepCompareImportFixes(context, fixer));
                         // Clean up now-unused React/useMemo imports if safe
-                        const sourceCode = context.getSourceCode();
+                        const sourceCode = context.sourceCode;
                         const program = sourceCode.ast;
                         const reactImport = program.body.find((n) => n.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
                             n.source.value === 'react');

package/lib/rules/prefer-usecallback-over-usememo-for-functions.js

@@ -166,7 +166,7 @@ function getMemoizedFunctionDescription(node) {
     return 'this callback value';
 }
 function reportAndFix(node, context) {
-    const sourceCode = context.getSourceCode();
+    const sourceCode = context.sourceCode;
     const useMemoCallback = node.arguments[0];
     const dependencyArray = node.arguments[1]
         ? sourceCode.getText(node.arguments[1])

package/lib/rules/prefer-utility-function-over-private-static.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferUtilityFunctionOverPrivateStatic = void 0;
 const createRule_1 = require("../utils/createRule");
+const getMethodName_1 = require("../utils/getMethodName");
 exports.preferUtilityFunctionOverPrivateStatic = (0, createRule_1.createRule)({
     name: 'prefer-utility-function-over-private-static',
     meta: {
@@ -12,7 +13,7 @@ exports.preferUtilityFunctionOverPrivateStatic = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            preferUtilityFunctionOverPrivateStatic: 'Private static methods should be abstracted into standalone utility functions for better reusability and testability',
+            preferUtilityFunctionOverPrivateStatic: 'Private static method "{{methodName}}" in class "{{className}}" does not use class state. Keeping class-agnostic helpers as private statics hides reusable logic and signals coupling that is not present. Extract this logic into a standalone utility function (module-level or shared) and import it where needed so it can be reused and unit tested independently.',
         },
     },
     defaultOptions: [],
@@ -47,9 +48,32 @@ exports.preferUtilityFunctionOverPrivateStatic = (0, createRule_1.createRule)({
             }
             return false;
         };
+        const getClassName = (method) => {
+            const classNode = method.parent?.parent;
+            if (classNode &&
+                (classNode.type === 'ClassDeclaration' ||
+                    classNode.type === 'ClassExpression')) {
+                if (classNode.id && classNode.id.type === 'Identifier') {
+                    return classNode.id.name;
+                }
+                if (classNode.type === 'ClassExpression' &&
+                    classNode.parent &&
+                    classNode.parent.type === 'VariableDeclarator' &&
+                    classNode.parent.id.type === 'Identifier') {
+                    return classNode.parent.id.name;
+                }
+                if (classNode.type === 'ClassExpression' &&
+                    classNode.parent &&
+                    classNode.parent.type === 'AssignmentExpression' &&
+                    classNode.parent.left.type === 'Identifier') {
+                    return classNode.parent.left.name;
+                }
+            }
+            return 'this class';
+        };
         return {
             'MethodDefinition[static=true][accessibility="private"]'(node) {
-                const sourceCode = context.getSourceCode();
+                const sourceCode = context.sourceCode;
                 const methodBody = node.value.body;
                 if (!methodBody) {
                     return;
@@ -65,9 +89,17 @@ exports.preferUtilityFunctionOverPrivateStatic = (0, createRule_1.createRule)({
                 const usesThis = hasThisReference(methodBody);
                 // If the method doesn't use 'this', it's a good candidate for extraction
                 if (!usesThis) {
+                    const methodName = (0, getMethodName_1.getMethodName)(node, sourceCode, {
+                        computedFallbackToText: false,
+                    }) || '<unknown>';
+                    const className = getClassName(node);
                     context.report({
                         node,
                         messageId: 'preferUtilityFunctionOverPrivateStatic',
+                        data: {
+                            methodName,
+                            className,
+                        },
                     });
                 }
             },

package/lib/rules/prevent-children-clobber.d.ts

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