@blumintinc/eslint-plugin-blumint 1.12.6 → 1.13.0

package/lib/rules/prefer-document-flattening.d.ts

@@ -0,0 +1,4 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type MessageIds = 'preferDocumentFlattening' | 'addShouldFlatten';
+export declare const preferDocumentFlattening: TSESLint.RuleModule<MessageIds, [], TSESLint.RuleListener>;
+export {};

package/lib/rules/prefer-document-flattening.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferDocumentFlattening = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+function isIdentifier(node) {
+    return node.type === utils_1.AST_NODE_TYPES.Identifier;
+}
+function isMemberExpression(node) {
+    return node.type === utils_1.AST_NODE_TYPES.MemberExpression;
+}
+function isObjectExpression(node) {
+    return node.type === utils_1.AST_NODE_TYPES.ObjectExpression;
+}
+function isProperty(node) {
+    return node.type === utils_1.AST_NODE_TYPES.Property;
+}
+/**
+ * Recursively checks if an object has deeply nested objects
+ */
+const hasDeepNestedObjects = (node) => {
+    if (isObjectExpression(node)) {
+        for (const property of node.properties) {
+            if (!isProperty(property))
+                continue;
+            const value = property.value;
+            // If the property value is an object, it's a nested object
+            if (isObjectExpression(value)) {
+                return true;
+            }
+            // Check arrays for nested objects
+            if (value.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+                for (const element of value.elements) {
+                    if (element && hasDeepNestedObjects(element)) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    // Check arrays for nested objects
+    if (node.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+        for (const element of node.elements) {
+            if (element && hasDeepNestedObjects(element)) {
+                return true;
+            }
+        }
+    }
+    return false;
+};
+exports.preferDocumentFlattening = (0, createRule_1.createRule)({
+    name: 'prefer-document-flattening',
+    meta: {
+        type: 'suggestion',
+        hasSuggestions: true,
+        docs: {
+            description: 'Enforce using the shouldFlatten option when setting deeply nested objects in Firestore documents',
+            recommended: 'error',
+        },
+        schema: [],
+        messages: {
+            preferDocumentFlattening: '{{className}} instance "{{instanceName}}" sets nested Firestore data without enabling shouldFlatten. Nested object writes overwrite sibling fields and require read-modify-write cycles, which increases contention and hides field-level query paths. Add shouldFlatten: true in the {{className}} options or pass flattened field paths (for example, "profile.settings.theme") so nested updates stay atomic and queryable.',
+            addShouldFlatten: 'Add shouldFlatten: true to the DocSetter options.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        // Track DocSetter instances without shouldFlatten option
+        const docSetterInstances = [];
+        // Track which DocSetter instances are used to set nested objects
+        const docSetterWithNestedObjects = new Set();
+        const buildSuggestion = (instance) => {
+            const newExpr = instance.node;
+            const hasOptionsArg = newExpr.arguments.length >= 2;
+            const optionsArg = hasOptionsArg ? newExpr.arguments[1] : undefined;
+            if (optionsArg && isObjectExpression(optionsArg)) {
+                const insertPos = (optionsArg.range?.[1] ?? optionsArg.parent?.range?.[1] ?? 0) - 1;
+                const prefix = optionsArg.properties.length ? ', ' : '';
+                return [
+                    {
+                        messageId: 'addShouldFlatten',
+                        fix(fixer) {
+                            return fixer.insertTextBeforeRange([insertPos, insertPos], `${prefix}shouldFlatten: true`);
+                        },
+                    },
+                ];
+            }
+            const endPos = (newExpr.range?.[1] ?? newExpr.parent?.range?.[1] ?? 0) - 1;
+            return [
+                {
+                    messageId: 'addShouldFlatten',
+                    fix(fixer) {
+                        return fixer.insertTextBeforeRange([endPos, endPos], `${hasOptionsArg ? '' : ','} { shouldFlatten: true }`);
+                    },
+                },
+            ];
+        };
+        return {
+            // Detect DocSetter and DocSetterTransaction instantiations
+            NewExpression(node) {
+                if (!isIdentifier(node.callee))
+                    return;
+                const className = node.callee.name;
+                // Only check DocSetter and DocSetterTransaction classes
+                if (className !== 'DocSetter' && className !== 'DocSetterTransaction')
+                    return;
+                // Check if shouldFlatten option is provided
+                let hasShouldFlatten = false;
+                // The options object is typically the second argument
+                if (node.arguments.length >= 2) {
+                    const optionsArg = node.arguments[1];
+                    if (isObjectExpression(optionsArg)) {
+                        for (const property of optionsArg.properties) {
+                            if (!isProperty(property))
+                                continue;
+                            if (isIdentifier(property.key) &&
+                                property.key.name === 'shouldFlatten' &&
+                                property.value.type === utils_1.AST_NODE_TYPES.Literal &&
+                                property.value.value === true) {
+                                hasShouldFlatten = true;
+                                break;
+                            }
+                        }
+                    }
+                }
+                // Get variable name from parent node if it's a variable declaration
+                let instanceName = '';
+                if (node.parent &&
+                    node.parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                    isIdentifier(node.parent.id)) {
+                    instanceName = node.parent.id.name;
+                }
+                if (instanceName && !hasShouldFlatten) {
+                    docSetterInstances.push({
+                        className,
+                        name: instanceName,
+                        node,
+                        hasShouldFlatten,
+                    });
+                }
+            },
+            // Check for set method calls on DocSetter instances
+            CallExpression(node) {
+                if (!isMemberExpression(node.callee))
+                    return;
+                const property = node.callee.property;
+                if (!isIdentifier(property))
+                    return;
+                // Check if it's a set or setAll method
+                if (property.name !== 'set' && property.name !== 'setAll')
+                    return;
+                const object = node.callee.object;
+                let instance;
+                if (isIdentifier(object)) {
+                    instance = docSetterInstances.find((i) => i.name === object.name);
+                }
+                else if (object.type === utils_1.AST_NODE_TYPES.NewExpression &&
+                    isIdentifier(object.callee)) {
+                    const className = object.callee.name;
+                    if (className === 'DocSetter' ||
+                        className === 'DocSetterTransaction') {
+                        let hasShouldFlatten = false;
+                        if (object.arguments.length >= 2) {
+                            const optionsArg = object.arguments[1];
+                            if (isObjectExpression(optionsArg)) {
+                                for (const property of optionsArg.properties) {
+                                    if (!isProperty(property))
+                                        continue;
+                                    if (isIdentifier(property.key) &&
+                                        property.key.name === 'shouldFlatten' &&
+                                        property.value.type === utils_1.AST_NODE_TYPES.Literal &&
+                                        property.value.value === true) {
+                                        hasShouldFlatten = true;
+                                        break;
+                                    }
+                                }
+                            }
+                        }
+                        if (!hasShouldFlatten) {
+                            instance = {
+                                className,
+                                name: `(inline-${docSetterInstances.length})`,
+                                node: object,
+                                hasShouldFlatten,
+                            };
+                            docSetterInstances.push(instance);
+                        }
+                    }
+                }
+                if (!instance)
+                    return;
+                // Check if we're setting a nested object
+                if (node.arguments.length > 0) {
+                    const dataArg = node.arguments[0];
+                    // For set method
+                    if (isObjectExpression(dataArg) && hasDeepNestedObjects(dataArg)) {
+                        docSetterWithNestedObjects.add(instance.name);
+                    }
+                    // For setAll method with array argument
+                    if (dataArg.type === utils_1.AST_NODE_TYPES.ArrayExpression &&
+                        dataArg.elements.some((element) => {
+                            if (!element || !isObjectExpression(element)) {
+                                return false;
+                            }
+                            for (const prop of element.properties) {
+                                if (!isProperty(prop) || !isIdentifier(prop.key))
+                                    continue;
+                                if (prop.key.name !== 'data')
+                                    continue;
+                                if (!isObjectExpression(prop.value))
+                                    return false;
+                                return hasDeepNestedObjects(prop.value);
+                            }
+                            return false;
+                        })) {
+                        docSetterWithNestedObjects.add(instance.name);
+                    }
+                }
+            },
+            // Report at the end of the program
+            'Program:exit'() {
+                for (const instance of docSetterInstances) {
+                    if (docSetterWithNestedObjects.has(instance.name)) {
+                        context.report({
+                            node: instance.node,
+                            messageId: 'preferDocumentFlattening',
+                            data: {
+                                className: instance.className,
+                                instanceName: instance.name,
+                            },
+                            suggest: buildSuggestion(instance),
+                        });
+                    }
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=prefer-document-flattening.js.map

package/lib/rules/prefer-field-paths-in-transforms.d.ts

@@ -0,0 +1,7 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+interface RuleOptions {
+    containers?: string[];
+    allowNestedIn?: string[];
+}
+export declare const preferFieldPathsInTransforms: TSESLint.RuleModule<"preferFieldPathsInTransforms", [(RuleOptions | undefined)?], TSESLint.RuleListener>;
+export {};

package/lib/rules/prefer-field-paths-in-transforms.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferFieldPathsInTransforms = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const minimatch_1 = require("minimatch");
+const createRule_1 = require("../utils/createRule");
+// Defaults aim to catch common BluMint aggregation container names
+const DEFAULT_CONTAINERS = ['*Aggregation', 'previews', '*Previews'];
+function describeNestedPath(containerValue) {
+    let objectFallback = null;
+    let primitiveFallback = null;
+    for (const prop of containerValue.properties) {
+        if (prop.type === utils_1.AST_NODE_TYPES.SpreadElement)
+            continue;
+        if (!isProperty(prop))
+            continue;
+        if (prop.computed)
+            continue;
+        const firstKey = getPropertyName(prop);
+        if (!firstKey)
+            continue;
+        if (isObjectExpression(prop.value)) {
+            for (const child of prop.value.properties) {
+                if (child.type === utils_1.AST_NODE_TYPES.SpreadElement)
+                    continue;
+                if (!isProperty(child))
+                    continue;
+                if (child.computed)
+                    continue;
+                const childKey = getPropertyName(child);
+                if (childKey)
+                    return `${firstKey}.${childKey}`;
+            }
+            // Object container without usable child keys still signals nested intent
+            if (!objectFallback)
+                objectFallback = firstKey;
+            continue;
+        }
+        if (!primitiveFallback)
+            primitiveFallback = firstKey;
+    }
+    return objectFallback ?? primitiveFallback;
+}
+function isObjectExpression(node) {
+    return !!node && node.type === utils_1.AST_NODE_TYPES.ObjectExpression;
+}
+function isProperty(node) {
+    return node.type === utils_1.AST_NODE_TYPES.Property;
+}
+function getPropertyName(node) {
+    if (node.computed)
+        return null;
+    if (node.key.type === utils_1.AST_NODE_TYPES.Identifier)
+        return node.key.name;
+    if (node.key.type === utils_1.AST_NODE_TYPES.Literal &&
+        typeof node.key.value === 'string')
+        return node.key.value;
+    return null;
+}
+function isNamedFunction(fn, name) {
+    if (fn.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+        return (!!fn.id && fn.id.type === utils_1.AST_NODE_TYPES.Identifier && fn.id.name === name);
+    }
+    // For function expressions, parent determines name association
+    return false;
+}
+function isBoundToName(fn, name) {
+    if (fn.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+        return isNamedFunction(fn, name);
+    }
+    const parent = fn.parent;
+    if (!parent)
+        return false;
+    if (parent.type === utils_1.AST_NODE_TYPES.Property ||
+        parent.type === utils_1.AST_NODE_TYPES.MethodDefinition ||
+        parent.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
+        const key = parent.key;
+        if (parent.computed) {
+            return key.type === utils_1.AST_NODE_TYPES.Literal && key.value === name;
+        }
+        if (key.type === utils_1.AST_NODE_TYPES.Identifier)
+            return key.name === name;
+        if (key.type === utils_1.AST_NODE_TYPES.Literal)
+            return key.value === name;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
+        return parent.id.type === utils_1.AST_NODE_TYPES.Identifier && parent.id.name === name;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.AssignmentExpression) {
+        const left = parent.left;
+        if (left.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+            const prop = left.property;
+            if (prop.type === utils_1.AST_NODE_TYPES.Identifier)
+                return prop.name === name;
+            if (prop.type === utils_1.AST_NODE_TYPES.Literal)
+                return prop.value === name;
+        }
+        else if (left.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return left.name === name;
+        }
+    }
+    return false;
+}
+function isTransformEachFunction(fn) {
+    return isBoundToName(fn, 'transformEach');
+}
+function isTransformEachVaripotent(fn) {
+    return isBoundToName(fn, 'transformEachVaripotent');
+}
+// Determine whether any path two or more levels below a container is created using object literals
+function hasDeeperThanOneLevelUnderContainer(containerObj) {
+    for (const prop of containerObj.properties) {
+        if (prop.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+            if (isObjectExpression(prop.argument)) {
+                return true;
+            }
+            continue;
+        }
+        if (!isProperty(prop))
+            continue;
+        const value = prop.value;
+        if (isObjectExpression(value)) {
+            // Any nested object literal implies depth >= 2 (even if it only spreads)
+            return true;
+        }
+    }
+    return false;
+}
+function analyzeReturnedObject(obj, context, containerNameMatches) {
+    for (const top of obj.properties) {
+        if (top.type === utils_1.AST_NODE_TYPES.SpreadElement)
+            continue;
+        if (!isProperty(top))
+            continue;
+        // Skip computed top-level keys and already-flattened keys containing dots
+        if (top.computed)
+            continue;
+        const keyName = getPropertyName(top);
+        if (!keyName)
+            continue;
+        if (keyName.includes('.'))
+            continue;
+        if (!containerNameMatches(keyName))
+            continue;
+        const containerValue = top.value;
+        if (!isObjectExpression(containerValue))
+            continue; // only care if returning an object under the container
+        if (hasDeeperThanOneLevelUnderContainer(containerValue)) {
+            const nestedPath = describeNestedPath(containerValue) ?? 'nestedField';
+            context.report({
+                node: top,
+                messageId: 'preferFieldPathsInTransforms',
+                data: {
+                    container: keyName,
+                    nestedPath,
+                    flattenedPath: `${keyName}.${nestedPath}`,
+                },
+                fix: () => null,
+            });
+        }
+    }
+}
+exports.preferFieldPathsInTransforms = (0, createRule_1.createRule)({
+    name: 'prefer-field-paths-in-transforms',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Flatten aggregation updates inside transformEach so diff-based deletes remove only the intended fields instead of wiping sibling data.',
+            recommended: 'warn',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    containers: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    allowNestedIn: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            preferFieldPathsInTransforms: 'Transform returns nested object under "{{container}}" (e.g., "{{nestedPath}}"). Nested writes in shared aggregation containers cause diff reconciliation to delete the whole subtree, wiping sibling fields. Flatten the update into field-path keys such as "{{flattenedPath}}" so only the intended leaf changes and other aggregation data stays intact.',
+        },
+    },
+    defaultOptions: [
+        {
+            containers: DEFAULT_CONTAINERS,
+            allowNestedIn: [],
+        },
+    ],
+    create(context, [options]) {
+        const filename = context.getFilename();
+        const resolvedOptions = options ?? {
+            containers: DEFAULT_CONTAINERS,
+            allowNestedIn: [],
+        };
+        const containers = resolvedOptions.containers ?? DEFAULT_CONTAINERS;
+        const allowNestedIn = resolvedOptions.allowNestedIn ?? [];
+        // Skip files explicitly allowed
+        if (allowNestedIn.length > 0 &&
+            allowNestedIn.some((glob) => (0, minimatch_1.minimatch)(filename, glob))) {
+            return {};
+        }
+        function containerNameMatches(name) {
+            return containers.some((pattern) => (0, minimatch_1.minimatch)(name, pattern));
+        }
+        function isInTargetTransform(returnNode) {
+            // Find nearest function ancestor
+            let current = returnNode.parent ?? null;
+            while (current) {
+                if (current.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                    current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                    current.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+                    const fn = current;
+                    if (isTransformEachVaripotent(fn))
+                        return false;
+                    if (isTransformEachFunction(fn))
+                        return true;
+                }
+                current = current.parent ?? null;
+            }
+            return false;
+        }
+        return {
+            ReturnStatement(node) {
+                if (!node.argument || !isObjectExpression(node.argument))
+                    return;
+                if (!isInTargetTransform(node))
+                    return;
+                analyzeReturnedObject(node.argument, context, containerNameMatches);
+            },
+            ArrowFunctionExpression(node) {
+                // Handle implicit returns: transformEach: doc => ({ ... })
+                if (!isTransformEachFunction(node) || isTransformEachVaripotent(node))
+                    return;
+                if (isObjectExpression(node.body)) {
+                    analyzeReturnedObject(node.body, context, containerNameMatches);
+                }
+            },
+        };
+    },
+});
+//# sourceMappingURL=prefer-field-paths-in-transforms.js.map

package/lib/rules/prefer-fragment-component.js

@@ -8,14 +8,14 @@ exports.preferFragmentComponent = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce using Fragment imported from react over shorthand fragments and React.Fragment',
+            description: 'Require the Fragment named import instead of shorthand fragments or React.Fragment to keep fragments explicit and prop-friendly',
             recommended: 'error',
         },
         fixable: 'code',
         schema: [],
         messages: {
-            preferFragment: 'Use Fragment imported from react instead of {{type}}',
-            addFragmentImport: 'Add Fragment import from react',
+            preferFragment: 'Prefer Fragment imported from react over {{type}}. Shorthand fragments block props like "key" and mixing fragment styles makes JSX harder to refactor. Import { Fragment } from "react" and wrap the children with <Fragment>...</Fragment> so fragment usage stays explicit.',
+            addFragmentImport: "Fragment is used but not imported from react. Without an explicit import the fixer leaves <Fragment> undefined and the React dependency implicit. Add `import { Fragment } from 'react'` alongside your other React imports so the file compiles.",
         },
     },
     defaultOptions: [],

package/lib/rules/prefer-global-router-state-key.d.ts

@@ -1,5 +1,9 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type MessageIds = 'preferGlobalRouterStateKey' | 'invalidQueryKeySource';
 /**
- * Rule to enforce best practices for the `key` parameter in `useRouterState` hook calls.
- * Encourages type safety and maintainability by using global constants or type-safe functions.
+ * Rule to enforce the use of centralized router state key constants imported from
+ * `src/util/routing/queryKeys.ts` instead of arbitrary string literals when calling
+ * router methods that accept key parameters.
  */
-export declare const preferGlobalRouterStateKey: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"preferGlobalRouterStateKey", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export declare const preferGlobalRouterStateKey: TSESLint.RuleModule<MessageIds, [], TSESLint.RuleListener>;
+export {};