@blumintinc/eslint-plugin-blumint 1.13.0 → 1.15.0

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

@@ -13,210 +13,259 @@ const HANDLER_TYPES = new Set([
     'RealtimeDbChangeHandler',
     'RealtimeDbChangeHandlerTransaction',
 ]);
-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: '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}}`).',
-        },
-    },
-    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;
+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;
         }
-        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;
+        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;
             }
-            return checkTypeAnnotationForHandler(typeAnnotation.typeAnnotation);
+            current = current.parent;
         }
-        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;
+    }
+    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;
         }
-        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 };
+        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 };
             }
-            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 };
+            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);
+                    }
                 }
-                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 };
+                return { properties };
             }
-            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;
+    }
+    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;
         }
-        function hasOptionalChaining(node) {
-            let current = node;
-            while (current && current.type === utils_1.AST_NODE_TYPES.MemberExpression) {
-                if (current.optional) {
-                    return true;
-                }
-                current = current.object;
+    }
+    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;
             }
-            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;
-                    });
+            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;
                 }
-                // 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;
-                                        });
-                                    }
-                                }
-                            }
-                        }
-                    }
+                const paramsInScope = findParamsInPattern(declarator.id);
+                if (paramsInScope) {
+                    return paramsInScope;
                 }
             }
-            return false;
         }
+    }
+    return null;
+};
+exports.preferParamsOverParentId = (0, createRule_1.createRule)({
+    name: 'prefer-params-over-parent-id',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer event.params over ref.parent.id for type-safe Firebase trigger paths.',
+            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)) {
-                    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

@@ -47,6 +47,7 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
     defaultOptions: [defaultOptions],
     create(context, [options]) {
         const finalOptions = { ...defaultOptions, ...options };
+        const { sourceCode } = context;
         function getParameterType(param) {
             if (param.type === utils_1.AST_NODE_TYPES.AssignmentPattern) {
                 return getParameterType(param.left);
@@ -56,13 +57,10 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                 const typeNode = param.typeAnnotation.typeAnnotation;
                 if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
                     // Include type parameters in the type signature to differentiate generic types
-                    const typeName = typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier
-                        ? typeNode.typeName.name
-                        : 'unknown';
+                    const typeName = sourceCode.getText(typeNode.typeName);
                     // If there are type parameters, include them in the type signature
                     if (typeNode.typeParameters &&
                         typeNode.typeParameters.params.length > 0) {
-                        const sourceCode = context.getSourceCode();
                         const typeParams = typeNode.typeParameters.params
                             .map((param) => sourceCode.getText(param))
                             .join(', ');
@@ -76,13 +74,10 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                 const typeNode = param.typeAnnotation.typeAnnotation;
                 if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
                     // Include type parameters in the type signature to differentiate generic types
-                    const typeName = typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier
-                        ? typeNode.typeName.name
-                        : 'unknown';
+                    const typeName = sourceCode.getText(typeNode.typeName);
                     // If there are type parameters, include them in the type signature
                     if (typeNode.typeParameters &&
                         typeNode.typeParameters.params.length > 0) {
-                        const sourceCode = context.getSourceCode();
                         const typeParams = typeNode.typeParameters.params
                             .map((param) => sourceCode.getText(param))
                             .join(', ');
@@ -98,12 +93,14 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                     return 'boolean';
                 return typeNode.type;
             }
-            return 'unknown';
+            return null;
         }
         function findDuplicateParameterType(params) {
             const typeMap = new Map();
             for (const param of params) {
                 const type = getParameterType(param);
+                if (type === null)
+                    continue;
                 const count = (typeMap.get(type) || 0) + 1;
                 typeMap.set(type, count);
                 if (count > 1) {
@@ -248,6 +245,24 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
             }
             return false;
         }
+        function hasImplicitlyTypedParams(params) {
+            return params.some((param) => {
+                let current = param;
+                if (current.type === utils_1.AST_NODE_TYPES.TSParameterProperty) {
+                    current = current.parameter;
+                }
+                if (current.type === utils_1.AST_NODE_TYPES.AssignmentPattern) {
+                    current = current.left;
+                }
+                if (current.type === utils_1.AST_NODE_TYPES.Identifier ||
+                    current.type === utils_1.AST_NODE_TYPES.ObjectPattern ||
+                    current.type === utils_1.AST_NODE_TYPES.ArrayPattern ||
+                    current.type === utils_1.AST_NODE_TYPES.RestElement) {
+                    return !current.typeAnnotation;
+                }
+                return true;
+            });
+        }
         function shouldIgnoreNode(node) {
             // Ignore built-in objects and third-party modules
             if (isBuiltInOrThirdParty(node))
@@ -270,7 +285,7 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                     parent = parent.parent;
                 }
             }
-            // Ignore functions with A/B pattern parameters
+            // Ignore functions with A/B pattern parameters or missing type annotations
             if ((node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
                 node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
                 node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
@@ -279,6 +294,8 @@ exports.preferSettingsObject = (0, createRule_1.createRule)({
                 Array.isArray(node.params)) {
                 if (hasABPattern(node.params))
                     return true;
+                if (hasImplicitlyTypedParams(node.params))
+                    return true;
             }
             // Check if the function is a handler with transaction parameter
             // This is a common pattern in Firebase/Firestore handlers

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

@@ -225,6 +225,15 @@ exports.preferTypeAliasOverTypeofConstant = (0, createRule_1.createRule)({
             TSTypeQuery(node) {
                 if (!collected)
                     return;
+                // Skip if inside a type alias declaration (Issue #1117)
+                // This allows 'type T = typeof CONST' as the canonical way to define the alias.
+                let current = node.parent;
+                while (current) {
+                    if (current.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+                        return;
+                    }
+                    current = current.parent;
+                }
                 // Skip `keyof typeof X`
                 if (node.parent &&
                     node.parent.type === utils_1.AST_NODE_TYPES.TSTypeOperator &&

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: [],