@blumintinc/eslint-plugin-blumint 1.12.6 → 1.14.0

package/lib/rules/no-res-error-status-in-onrequest.js

@@ -0,0 +1,521 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireHttpsErrorInOnRequestHandlers = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const ON_REQUEST_MODULE = 'functions/src/v2/https/onRequest';
+const HTTPS_ERROR_IMPORT_PATH = 'functions/src/util/errors/HttpsError';
+const isFunctionLike = (node) => !!node &&
+    (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression);
+const isIdentifierWithName = (node, name) => !!node && node.type === utils_1.AST_NODE_TYPES.Identifier && node.name === name;
+const unwrapTypedExpression = (expression) => {
+    let current = expression;
+    while (current.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+        current.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+        current.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+        current.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+        current.type === utils_1.AST_NODE_TYPES.TSInstantiationExpression) {
+        current = current.expression;
+    }
+    return current;
+};
+const getResponseParamNames = (node) => {
+    const RESPONSE_PARAM_KEYS = new Set(['res', 'response', 'resp']);
+    const extractName = (param) => {
+        if (param.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return { name: param.name, isExplicitResponseBinding: false };
+        }
+        if (param.type === utils_1.AST_NODE_TYPES.AssignmentPattern &&
+            param.left.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return { name: param.left.name, isExplicitResponseBinding: false };
+        }
+        if (param.type === utils_1.AST_NODE_TYPES.RestElement &&
+            param.argument.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return { name: param.argument.name, isExplicitResponseBinding: false };
+        }
+        if (param.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
+            for (const property of param.properties) {
+                if (property.type !== utils_1.AST_NODE_TYPES.Property || property.computed) {
+                    continue;
+                }
+                const keyName = property.key.type === utils_1.AST_NODE_TYPES.Identifier
+                    ? property.key.name
+                    : property.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                        typeof property.key.value === 'string'
+                        ? property.key.value
+                        : null;
+                if (!keyName || !RESPONSE_PARAM_KEYS.has(keyName.toLowerCase())) {
+                    continue;
+                }
+                if (property.value.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return { name: property.value.name, isExplicitResponseBinding: true };
+                }
+                if (property.value.type === utils_1.AST_NODE_TYPES.AssignmentPattern &&
+                    property.value.left.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return {
+                        name: property.value.left.name,
+                        isExplicitResponseBinding: true,
+                    };
+                }
+            }
+            return null;
+        }
+        if (param.type === utils_1.AST_NODE_TYPES.ArrayPattern) {
+            for (const element of param.elements) {
+                if (!element) {
+                    continue;
+                }
+                const name = element.type === utils_1.AST_NODE_TYPES.Identifier
+                    ? element.name
+                    : element.type === utils_1.AST_NODE_TYPES.AssignmentPattern &&
+                        element.left.type === utils_1.AST_NODE_TYPES.Identifier
+                        ? element.left.name
+                        : element.type === utils_1.AST_NODE_TYPES.RestElement &&
+                            element.argument.type === utils_1.AST_NODE_TYPES.Identifier
+                            ? element.argument.name
+                            : null;
+                if (name && RESPONSE_PARAM_KEYS.has(name.toLowerCase())) {
+                    return { name, isExplicitResponseBinding: false };
+                }
+            }
+            return null;
+        }
+        return null;
+    };
+    return node.params.reduce((acc, param, index) => {
+        const extracted = extractName(param);
+        if (!extracted)
+            return acc;
+        const lowered = extracted.name.toLowerCase();
+        const likelyResponse = extracted.isExplicitResponseBinding || RESPONSE_PARAM_KEYS.has(lowered);
+        /**
+         * In typical Express handlers, the response param is the second argument (req, res),
+         * so we treat the second parameter as a likely response name even if it doesn't match
+         * 'res', 'response', or 'resp'.
+         */
+        if (likelyResponse || index === 1) {
+            acc.push(extracted.name);
+        }
+        return acc;
+    }, []);
+};
+const getStatusCodeFromArg = (arg) => {
+    if (!arg || arg.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+        return null;
+    }
+    if (arg.type === utils_1.AST_NODE_TYPES.Literal && typeof arg.value === 'number') {
+        return arg.value;
+    }
+    return null;
+};
+const mapStatusToHttpsCode = (status) => {
+    if (status === 400)
+        return 'invalid-argument';
+    if (status === 401)
+        return 'unauthenticated';
+    if (status === 403)
+        return 'permission-denied';
+    if (status === 404)
+        return 'not-found';
+    if (status === 409)
+        return 'already-exists';
+    if (status === 412 || status === 422)
+        return 'failed-precondition';
+    if (status === 429)
+        return 'resource-exhausted';
+    if (status === 499 || status === 504)
+        return 'deadline-exceeded';
+    if (status === 500)
+        return 'internal';
+    if (status === 502 || status === 503)
+        return 'unavailable';
+    return 'unknown';
+};
+const findNearestFunction = (ancestors) => {
+    for (let idx = ancestors.length - 1; idx >= 0; idx -= 1) {
+        const ancestor = ancestors[idx];
+        if (isFunctionLike(ancestor)) {
+            return ancestor;
+        }
+    }
+    return null;
+};
+const getMessageExample = (call) => {
+    const firstArg = call.arguments[0];
+    if (firstArg &&
+        firstArg.type === utils_1.AST_NODE_TYPES.Literal &&
+        typeof firstArg.value === 'string') {
+        return firstArg.value;
+    }
+    if (firstArg &&
+        firstArg.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
+        firstArg.expressions.length === 0) {
+        return firstArg.quasis.map((part) => part.value.raw).join('');
+    }
+    return 'provide a descriptive message';
+};
+const getObjectNameFromExpression = (node) => {
+    if (node.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.name;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !node.computed &&
+        node.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        node.object.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return `${node.object.name}.${node.property.name}`;
+    }
+    return null;
+};
+const getCalleeDisplayName = (callee) => {
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.name;
+    }
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        const objectName = getObjectNameFromExpression(callee.object);
+        if (objectName) {
+            return `${objectName}.${callee.property.name}`;
+        }
+        return callee.property.name;
+    }
+    return 'helper';
+};
+const getIdentifierNameFromExpression = (expression) => {
+    if (expression.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return expression.name;
+    }
+    if (expression.type === utils_1.AST_NODE_TYPES.PrivateIdentifier) {
+        return null;
+    }
+    const unwrapped = unwrapTypedExpression(expression);
+    return unwrapped.type === utils_1.AST_NODE_TYPES.Identifier ? unwrapped.name : null;
+};
+const isStatusMember = (member, propertyName) => {
+    if (member.computed ||
+        member.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+        member.property.name !== propertyName) {
+        return null;
+    }
+    const responseName = getIdentifierNameFromExpression(member.object);
+    return responseName ? { responseName } : null;
+};
+const getStatusInfoFromStatusCall = (call) => {
+    if (call.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        const statusMember = isStatusMember(call.callee, 'status');
+        if (!statusMember) {
+            return null;
+        }
+        return {
+            responseName: statusMember.responseName,
+            statusCode: getStatusCodeFromArg(call.arguments[0]),
+        };
+    }
+    return null;
+};
+const findStatusCall = (node) => {
+    if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        const sendStatusMember = isStatusMember(node.callee, 'sendStatus');
+        if (sendStatusMember) {
+            return {
+                responseName: sendStatusMember.responseName,
+                statusCode: getStatusCodeFromArg(node.arguments[0]),
+                method: 'sendStatus',
+            };
+        }
+    }
+    if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        const statusMember = isStatusMember(node.callee, 'status');
+        if (statusMember) {
+            const parent = node.parent;
+            if (parent &&
+                parent.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                parent.object === node &&
+                parent.parent &&
+                parent.parent.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                return null;
+            }
+            return {
+                responseName: statusMember.responseName,
+                statusCode: getStatusCodeFromArg(node.arguments[0]),
+                method: 'status',
+            };
+        }
+    }
+    if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        node.callee.object.type === utils_1.AST_NODE_TYPES.CallExpression) {
+        const statusInfo = getStatusInfoFromStatusCall(node.callee.object);
+        if (!statusInfo) {
+            return null;
+        }
+        const method = node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier
+            ? node.callee.property.name
+            : 'status';
+        return {
+            ...statusInfo,
+            method,
+        };
+    }
+    return null;
+};
+const isErrorStatus = (statusCode) => statusCode === null || statusCode >= 400;
+exports.requireHttpsErrorInOnRequestHandlers = (0, createRule_1.createRule)({
+    name: 'no-res-error-status-in-onrequest',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Forbid sending 4xx/5xx Express responses inside onRequest handlers; throw structured HttpsError instances instead so the wrapper can format, log, and map errors consistently.',
+            recommended: 'error',
+        },
+        schema: [],
+        messages: {
+            useHttpsErrorForStatus: "HTTP status {{statusCode}} sent via `{{responseName}}.{{method}}` inside an onRequest handler bypasses the centralized HttpsError pipeline → This creates observability gaps (errors won't appear in structured logs), inconsistent client error shapes (breaking API contracts), and missing error context (details object unavailable for debugging). → Throw new HttpsError('{{httpsCode}}', '{{messageExample}}', details) instead and import HttpsError from {{httpsErrorImport}} so the wrapper captures context, logs structured data, and returns consistent error responses.",
+            useHttpsErrorForComputedStatus: "Computed HTTP status sent via `{{responseName}}.{{method}}` inside an onRequest handler cannot be mapped to the expected HttpsError codes → This bypasses the HttpsError pipeline, leading to inconsistent error logging and unstandardized response shapes. → Choose an explicit HttpsError code (e.g., 'invalid-argument', 'permission-denied') and throw new HttpsError('{{httpsCode}}', '{{messageExample}}', details) after importing from {{httpsErrorImport}} so the wrapper can standardize logging, capture error context, and maintain a consistent API contract.",
+            useHttpsErrorForWrapper: "`{{calleeName}}` receives the Express response object `{{responseName}}` inside an onRequest handler, which writes HTTP errors directly and skips the HttpsError wrapper → This results in missing structured logs, inconsistent error responses for clients, and makes debugging difficult due to lost error context. → Refactor this helper to throw new HttpsError('{{httpsCode}}', '{{messageExample}}', details) (import from {{httpsErrorImport}}) so the onRequest wrapper can handle formatting, status mapping, and centralized logging.",
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const onRequestIdentifiers = new Set();
+        const onRequestNamespaces = new Set();
+        const handlerFunctions = new Set();
+        const responseNamesByFunction = new Map();
+        const pendingViolations = [];
+        const recordFunction = (node) => {
+            responseNamesByFunction.set(node, getResponseParamNames(node));
+        };
+        const extractFunctionFromDefinition = (def) => {
+            const defNode = def.node;
+            if (isFunctionLike(defNode)) {
+                return defNode;
+            }
+            if (defNode.type === utils_1.AST_NODE_TYPES.VariableDeclarator && defNode.init) {
+                const initializer = unwrapTypedExpression(defNode.init);
+                if (isFunctionLike(initializer)) {
+                    return initializer;
+                }
+            }
+            return null;
+        };
+        const resolveFunctionFromIdentifier = (identifier) => {
+            let scope = context.getScope();
+            while (scope) {
+                const variable = scope.set.get(identifier.name) ??
+                    scope.variables.find((candidate) => candidate.name === identifier.name);
+                if (variable) {
+                    for (const def of variable.defs) {
+                        const fn = extractFunctionFromDefinition(def);
+                        if (fn) {
+                            return fn;
+                        }
+                    }
+                }
+                scope = scope.upper;
+            }
+            return null;
+        };
+        const isDirectOnRequestHandler = (fn) => {
+            return handlerFunctions.has(fn);
+        };
+        function findInFunctionChain(startNode, callback) {
+            let current = startNode;
+            while (current) {
+                if (isFunctionLike(current)) {
+                    const result = callback(current);
+                    if (result) {
+                        return result;
+                    }
+                }
+                current = current.parent;
+            }
+            return null;
+        }
+        const isWithinOnRequest = (fn) => !!findInFunctionChain(fn, (current) => isDirectOnRequestHandler(current));
+        const hasResponseBinding = (fn, responseName) => !!findInFunctionChain(fn, (current) => {
+            const params = responseNamesByFunction.get(current) ?? [];
+            return params.includes(responseName);
+        });
+        const findResponseIdentifierInArgs = (fn, call) => findInFunctionChain(fn, (current) => {
+            const params = responseNamesByFunction.get(current) ?? [];
+            return params.find((name) => call.arguments.some((arg) => {
+                const unwrapped = unwrapTypedExpression(arg);
+                return isIdentifierWithName(unwrapped, name);
+            }));
+        });
+        const handleOnRequestTracking = (node) => {
+            const isOnRequestCallee = (callee) => {
+                if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return onRequestIdentifiers.has(callee.name);
+                }
+                if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                    !callee.computed &&
+                    callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    callee.property.name === 'onRequest' &&
+                    callee.object.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return onRequestNamespaces.has(callee.object.name);
+                }
+                return false;
+            };
+            if (isOnRequestCallee(node.callee)) {
+                const handlerArg = [...node.arguments]
+                    .reverse()
+                    .find((arg) => arg.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                    arg.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                    arg.type === utils_1.AST_NODE_TYPES.Identifier ||
+                    arg.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+                    arg.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+                    arg.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+                    arg.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+                    arg.type === utils_1.AST_NODE_TYPES.TSInstantiationExpression);
+                if (handlerArg) {
+                    const expression = unwrapTypedExpression(handlerArg);
+                    if (isFunctionLike(expression)) {
+                        handlerFunctions.add(expression);
+                    }
+                    else if (expression.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        const resolvedHandler = resolveFunctionFromIdentifier(expression);
+                        if (resolvedHandler) {
+                            handlerFunctions.add(resolvedHandler);
+                        }
+                    }
+                }
+            }
+        };
+        const handleStatusViolation = (node) => {
+            const statusInfo = findStatusCall(node);
+            if (!statusInfo) {
+                return false;
+            }
+            const { responseName, statusCode, method } = statusInfo;
+            if (!isErrorStatus(statusCode)) {
+                return true;
+            }
+            const functionNode = findNearestFunction(ASTHelpers_1.ASTHelpers.getAncestors(context, node));
+            if (!functionNode) {
+                return true;
+            }
+            if (!hasResponseBinding(functionNode, responseName)) {
+                return true;
+            }
+            pendingViolations.push({
+                node,
+                functionNode,
+                responseName,
+                kind: statusCode === null ? 'computedStatus' : 'status',
+                statusCode,
+                method,
+                messageExample: getMessageExample(node),
+            });
+            return true;
+        };
+        const handleWrapperViolation = (node) => {
+            const functionNode = findNearestFunction(ASTHelpers_1.ASTHelpers.getAncestors(context, node));
+            if (!functionNode) {
+                return;
+            }
+            const responseName = findResponseIdentifierInArgs(functionNode, node);
+            /**
+             * Skip direct method calls on the response object (e.g., res.send(res)) so the
+             * wrapper detection only reports helpers that receive the response object as
+             * an argument.
+             */
+            const calleeUsesResponseDirectly = node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                node.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+                responseName === node.callee.object.name;
+            if (!responseName || calleeUsesResponseDirectly) {
+                return;
+            }
+            pendingViolations.push({
+                node,
+                functionNode,
+                responseName,
+                kind: 'wrapper',
+                statusCode: null,
+                method: 'wrapper',
+                messageExample: getMessageExample(node),
+                calleeName: getCalleeDisplayName(node.callee),
+            });
+        };
+        return {
+            ImportDeclaration(node) {
+                if (node.source.value !== ON_REQUEST_MODULE) {
+                    return;
+                }
+                node.specifiers.forEach((specifier) => {
+                    if (specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier) {
+                        onRequestIdentifiers.add(specifier.local.name);
+                    }
+                    else if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                        specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        specifier.imported.name === 'onRequest') {
+                        onRequestIdentifiers.add(specifier.local.name);
+                    }
+                    else if (specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+                        onRequestNamespaces.add(specifier.local.name);
+                    }
+                });
+            },
+            FunctionDeclaration: recordFunction,
+            FunctionExpression: recordFunction,
+            ArrowFunctionExpression: recordFunction,
+            CallExpression(node) {
+                handleOnRequestTracking(node);
+                if (handleStatusViolation(node)) {
+                    return;
+                }
+                handleWrapperViolation(node);
+            },
+            'Program:exit'() {
+                pendingViolations.forEach((violation) => {
+                    if (!isWithinOnRequest(violation.functionNode)) {
+                        return;
+                    }
+                    const httpsCode = mapStatusToHttpsCode(violation.statusCode);
+                    const commonData = {
+                        responseName: violation.responseName,
+                        messageExample: violation.messageExample,
+                        httpsCode,
+                        httpsErrorImport: HTTPS_ERROR_IMPORT_PATH,
+                    };
+                    if (violation.kind === 'wrapper') {
+                        context.report({
+                            node: violation.node,
+                            messageId: 'useHttpsErrorForWrapper',
+                            data: {
+                                ...commonData,
+                                calleeName: violation.calleeName ?? 'helper',
+                            },
+                        });
+                        return;
+                    }
+                    if (violation.kind === 'computedStatus') {
+                        context.report({
+                            node: violation.node,
+                            messageId: 'useHttpsErrorForComputedStatus',
+                            data: {
+                                ...commonData,
+                                method: violation.method,
+                            },
+                        });
+                        return;
+                    }
+                    context.report({
+                        node: violation.node,
+                        messageId: 'useHttpsErrorForStatus',
+                        data: {
+                            ...commonData,
+                            method: violation.method,
+                            statusCode: violation.statusCode !== null
+                                ? violation.statusCode.toString()
+                                : 'computed status',
+                        },
+                    });
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=no-res-error-status-in-onrequest.js.map

package/lib/rules/no-restricted-properties-fix.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This rule is a wrapper around the core ESLint no-restricted-properties rule
+ * that adds special handling for Object.keys() and Object.values() results.
+ * It prevents false positives when accessing standard array properties/methods
+ * on the arrays returned by Object.keys() and Object.values().
+ */
+export declare const noRestrictedPropertiesFix: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"restrictedProperty", [{
+    object?: string | undefined;
+    property?: string | undefined;
+    message?: string | undefined;
+    allowObjects?: string[] | undefined;
+}[]], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;