@blumintinc/eslint-plugin-blumint 1.12.6 → 1.13.0

package/lib/rules/enforce-dynamic-firebase-imports.js

@@ -7,41 +7,122 @@ exports.enforceFirebaseImports = (0, createRule_1.createRule)({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Enforce dynamic importing for modules within the firebaseCloud directory to optimize initial bundle size. This ensures Firebase-related code is only loaded when needed, improving application startup time and reducing the main bundle size.',
+            description: 'Require firebaseCloud modules to be loaded via dynamic import so Firebase code stays out of the initial bundle and only loads when needed.',
             recommended: 'error',
         },
+        fixable: 'code',
+        hasSuggestions: true,
         schema: [],
         messages: {
-            noDynamicImport: 'Static imports from firebaseCloud directory are not allowed to reduce initial bundle size. Instead of `import { func } from "./firebaseCloud/module"`, use dynamic import: `const { func } = await import("./firebaseCloud/module")`.',
+            noDynamicImport: 'Static import from firebaseCloud path "{{importPath}}" eagerly bundles Firebase code into the initial client chunk, which inflates startup time and prevents lazy loading. Replace it with an awaited dynamic import so the code only loads when invoked (e.g., `const module = await import(\'{{importPath}}\')` or destructure the exports you need).',
         },
     },
     defaultOptions: [],
     create(context) {
         return {
             ImportDeclaration(node) {
-                // Skip type-only imports
+                // Skip third-party files
+                const filename = context.getFilename?.();
+                if (filename && /(^|[\\/])node_modules([\\/]|$)/.test(filename)) {
+                    return;
+                }
+                // Skip type-only import declarations
                 if (node.importKind === 'type') {
                     return;
                 }
                 const importPath = node.source.value;
                 // Check if the import is from firebaseCloud directory
-                if (importPath.includes('firebaseCloud/')) {
-                    context.report({
-                        node,
-                        messageId: 'noDynamicImport',
-                        fix(fixer) {
-                            const importSpecifiers = node.specifiers
-                                .filter((spec) => spec.type === 'ImportSpecifier')
-                                .map((spec) => spec.imported.name);
-                            if (importSpecifiers.length === 0) {
-                                return null;
-                            }
-                            const destructuredImports = `{ ${importSpecifiers.join(', ')} }`;
-                            const dynamicImport = `const ${destructuredImports} = await import('${importPath}');`;
-                            return fixer.replaceText(node, dynamicImport);
-                        },
-                    });
+                if (!importPath.includes('firebaseCloud/')) {
+                    return;
                 }
+                // Determine specifiers
+                const defaultSpecifier = node.specifiers.find((spec) => spec.type === 'ImportDefaultSpecifier');
+                const namespaceSpecifier = node.specifiers.find((spec) => spec.type === 'ImportNamespaceSpecifier');
+                const namedSpecifiers = node.specifiers.filter((spec) => spec.type === 'ImportSpecifier' && spec.importKind !== 'type');
+                const typeOnlySpecifiers = node.specifiers.filter((spec) => spec.type === 'ImportSpecifier' && spec.importKind === 'type');
+                // If there are only type-only specifiers, allow
+                if (!defaultSpecifier &&
+                    !namespaceSpecifier &&
+                    namedSpecifiers.length === 0 &&
+                    typeOnlySpecifiers.length > 0) {
+                    return;
+                }
+                const buildTypeNames = () => typeOnlySpecifiers
+                    .map((spec) => spec.imported.name === spec.local.name
+                    ? spec.imported.name
+                    : `${spec.imported.name} as ${spec.local.name}`)
+                    .join(', ');
+                const buildReplacement = (options = {}) => {
+                    const statements = [];
+                    if (typeOnlySpecifiers.length > 0) {
+                        statements.push(`import type { ${buildTypeNames()} } from '${importPath}';`);
+                    }
+                    if (namespaceSpecifier) {
+                        const nsLocal = namespaceSpecifier.local.name;
+                        statements.push(`const ${nsLocal} = await import('${importPath}');`);
+                        if (defaultSpecifier) {
+                            const defLocal = defaultSpecifier.local.name;
+                            statements.push(`const ${defLocal} = ${nsLocal}.default;`);
+                        }
+                        const destructureFromNamespace = [];
+                        if (namedSpecifiers.length > 0) {
+                            const destructureParts = namedSpecifiers.map((spec) => {
+                                const imported = spec.imported.name;
+                                const local = spec.local.name;
+                                return imported === local ? imported : `${imported}: ${local}`;
+                            });
+                            destructureFromNamespace.push(...destructureParts);
+                        }
+                        if (destructureFromNamespace.length > 0) {
+                            statements.push(`const { ${destructureFromNamespace.join(', ')} } = ${nsLocal};`);
+                        }
+                        return statements.join(' ');
+                    }
+                    const destructureParts = [];
+                    if (defaultSpecifier) {
+                        const defLocal = defaultSpecifier.local.name;
+                        destructureParts.push(`default: ${defLocal}`);
+                    }
+                    if (namedSpecifiers.length > 0) {
+                        for (const spec of namedSpecifiers) {
+                            const imported = spec.imported.name;
+                            const local = spec.local.name;
+                            destructureParts.push(imported === local ? imported : `${imported}: ${local}`);
+                        }
+                    }
+                    if (destructureParts.length > 0) {
+                        statements.push(`const { ${destructureParts.join(', ')} } = await import('${importPath}');`);
+                        return statements.join(' ');
+                    }
+                    if (node.specifiers.length === 0) {
+                        return options.allowSideEffectFix !== false
+                            ? `await import('${importPath}');`
+                            : null;
+                    }
+                    return null;
+                };
+                context.report({
+                    node,
+                    messageId: 'noDynamicImport',
+                    data: { importPath },
+                    fix(fixer) {
+                        const replacement = buildReplacement();
+                        return replacement ? fixer.replaceText(node, replacement) : null;
+                    },
+                    suggest: [
+                        {
+                            messageId: 'noDynamicImport',
+                            fix(fixer) {
+                                const replacement = buildReplacement({
+                                    allowSideEffectFix: true,
+                                });
+                                return replacement
+                                    ? fixer.replaceText(node, replacement)
+                                    : null;
+                            },
+                        },
+                    ],
+                });
             },
         };
     },

package/lib/rules/enforce-dynamic-imports.js

@@ -29,7 +29,7 @@ exports.default = (0, createRule_1.createRule)({
             },
         ],
         messages: {
-            dynamicImportRequired: 'Static imports from "{{source}}" are not allowed to reduce initial bundle size. Use dynamic imports instead: const Component = useDynamic(() => import("{{source}}").then(mod => mod.Component))',
+            dynamicImportRequired: 'Static import from "{{source}}" eagerly pulls the entire package into the entry bundle, inflating download size and delaying the first render. Load it lazily with a dynamic import (for example, useDynamic(() => import("{{source}}"))) so the code is fetched only when needed; if you only need types, use a type-only import with allowImportType enabled.',
         },
     },
     defaultOptions: [

package/lib/rules/enforce-exported-function-types.js

@@ -14,9 +14,9 @@ exports.enforceExportedFunctionTypes = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            missingExportedType: 'Type {{typeName}} should be exported since it is used in an exported function. Add `export` before the type definition: `export type {{typeName}} = ...`',
-            missingExportedReturnType: 'Return type {{typeName}} should be exported since it is used in an exported function. Add `export` before the type definition: `export type {{typeName}} = ...`',
-            missingExportedPropsType: 'Props type {{typeName}} should be exported since it is used in an exported React component. Add `export` before the type definition: `export type {{typeName}} = ...`',
+            missingExportedType: 'Type "{{typeName}}" is used in a parameter of an exported function but is not exported. Callers cannot import the parameter contract, which forces duplicate or ad-hoc types and makes the API drift. Export the type (e.g., `export type {{typeName}} = ...`) or reuse an already exported type.',
+            missingExportedReturnType: 'Return type "{{typeName}}" belongs to an exported function but is not exported. Consumers cannot reference the returned shape for validation or composition, which leads to duplicated types and diverging contracts. Export the return type alias or interface so callers can import the shared contract.',
+            missingExportedPropsType: 'Props type "{{typeName}}" is used by an exported React component but is not exported. Other modules cannot type the props when composing the component and end up recreating the shape. Export the props type (e.g., `export type {{typeName}} = ...`) or reference an existing exported props contract.',
         },
     },
     defaultOptions: [],

package/lib/rules/enforce-fieldpath-syntax-in-docsetter.d.ts

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

package/lib/rules/enforce-fieldpath-syntax-in-docsetter.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceFieldPathSyntaxInDocSetter = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+exports.enforceFieldPathSyntaxInDocSetter = (0, createRule_1.createRule)({
+    name: 'enforce-fieldpath-syntax-in-docsetter',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce the use of Firestore FieldPath syntax when passing documentData into DocSetter. Instead of using nested object syntax, developers should use dot notation for deeply nested fields.',
+            recommended: 'error',
+            requiresTypeChecking: false,
+            extendsBaseRule: false,
+        },
+        fixable: 'code',
+        schema: [],
+        messages: {
+            enforceFieldPathSyntax: 'Use FieldPath syntax (dot notation) for nested fields in DocSetter. Instead of `{ roles: { contributor: value } }`, use `{ "roles.contributor": value }`.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        // Track DocSetter variables
+        const docSetterVariables = new Set();
+        // Helper function to check if a node is a DocSetter method call
+        function isDocSetterMethodCall(node) {
+            if (node.callee.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+                return false;
+            }
+            const { object, property } = node.callee;
+            // Only enforce for set/updateIfExists; skip overwrite (full-document replacement)
+            if (property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !['set', 'updateIfExists'].includes(property.name)) {
+                return false;
+            }
+            // Check if the object is a DocSetter instance
+            if (object.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return docSetterVariables.has(object.name);
+            }
+            // Support chained instantiation: new DocSetter(...).set(...)
+            if (object.type === utils_1.AST_NODE_TYPES.NewExpression &&
+                object.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                object.callee.name === 'DocSetter') {
+                return true;
+            }
+            return false;
+        }
+        // Helper: detect spread or computed properties in an object literal
+        function isSpreadOrComputed(prop) {
+            return (prop.type === utils_1.AST_NODE_TYPES.SpreadElement ||
+                (prop.type === utils_1.AST_NODE_TYPES.Property && prop.computed === true));
+        }
+        // Helper function to check if an object has nested objects (excluding arrays)
+        function hasNestedObjects(node, prefix = '') {
+            for (const property of node.properties) {
+                // Skip spread elements
+                if (property.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+                    continue;
+                }
+                if (property.type !== utils_1.AST_NODE_TYPES.Property) {
+                    continue;
+                }
+                // Skip computed properties (dynamic keys)
+                if (property.computed) {
+                    continue;
+                }
+                const isNumericKey = property.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                    (typeof property.key.value === 'number' ||
+                        (typeof property.key.value === 'string' &&
+                            /^\d+$/.test(property.key.value)));
+                // Allow top-level numeric keys (treated like array indexes)
+                if (prefix === '' && isNumericKey) {
+                    continue;
+                }
+                const value = property.value;
+                // Skip if the property key is already using dot notation
+                if (property.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                    typeof property.key.value === 'string' &&
+                    property.key.value.includes('.')) {
+                    continue;
+                }
+                // Check if the value is an object (but not an array)
+                if (value.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    // Skip nested objects that contain spread elements or computed properties
+                    const hasSpreadOrComputed = value.properties.some((prop) => isSpreadOrComputed(prop));
+                    if (!hasSpreadOrComputed) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        }
+        // Helper function to flatten nested objects into FieldPath syntax
+        function flattenObject(obj, sourceCode, prefix = '') {
+            const result = {};
+            for (const property of obj.properties) {
+                // Skip spread elements
+                if (property.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+                    continue;
+                }
+                if (property.type !== utils_1.AST_NODE_TYPES.Property) {
+                    continue;
+                }
+                // Skip computed properties (dynamic keys)
+                if (property.computed) {
+                    continue;
+                }
+                let key;
+                if (property.key.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    key = property.key.name;
+                }
+                else if (property.key.type === utils_1.AST_NODE_TYPES.Literal) {
+                    // Handle both string and numeric literal keys
+                    if (typeof property.key.value === 'string') {
+                        key = property.key.value;
+                    }
+                    else if (typeof property.key.value === 'number') {
+                        key = String(property.key.value);
+                    }
+                    else {
+                        // Skip other literal types
+                        continue;
+                    }
+                }
+                else {
+                    // Skip other key types
+                    continue;
+                }
+                const isNumericKey = property.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                    (typeof property.key.value === 'number' ||
+                        (typeof property.key.value === 'string' &&
+                            /^\d+$/.test(property.key.value)));
+                if (prefix === '' && isNumericKey) {
+                    continue;
+                }
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                // If the value is a nested object, recursively flatten it
+                if (property.value.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    const nestedResult = flattenObject(property.value, sourceCode, fullKey);
+                    Object.assign(result, nestedResult);
+                }
+                else {
+                    // For non-object values, use the key as is
+                    result[fullKey] = sourceCode.getText(property.value);
+                }
+            }
+            return result;
+        }
+        // Helper to decide if a key needs quoting (contains dot or is not IdentifierName)
+        function needsQuoting(key) {
+            return key.includes('.') || !/^(?:[$_A-Za-z][$\w]*)$/u.test(key);
+        }
+        // Helper function to convert an object to FieldPath syntax
+        function convertToFieldPathSyntax(node, sourceCode) {
+            const idProperty = node.properties.find((prop) => prop.type === utils_1.AST_NODE_TYPES.Property &&
+                prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                prop.key.name === 'id');
+            const flattenedProperties = flattenObject(node, sourceCode);
+            if (idProperty && idProperty.type === utils_1.AST_NODE_TYPES.Property) {
+                delete flattenedProperties['id'];
+            }
+            const entries = Object.entries(flattenedProperties);
+            const propertyComma = ',';
+            // Start with the id property if it exists
+            let result = '{\n';
+            if (idProperty && idProperty.type === utils_1.AST_NODE_TYPES.Property) {
+                result += `  id: ${sourceCode.getText(idProperty.value)}${propertyComma}\n`;
+            }
+            // Add the flattened properties (always include trailing commas for multiline objects)
+            entries.forEach(([key, value]) => {
+                const printedKey = needsQuoting(key) ? `'${key}'` : key;
+                result += `  ${printedKey}: ${value}${propertyComma}\n`;
+            });
+            result += '}';
+            return result;
+        }
+        return {
+            // Track DocSetter variable declarations
+            VariableDeclarator(node) {
+                if (node.init?.type === utils_1.AST_NODE_TYPES.NewExpression &&
+                    node.init.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.init.callee.name === 'DocSetter' &&
+                    node.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    docSetterVariables.add(node.id.name);
+                }
+            },
+            // Check DocSetter method calls
+            CallExpression(node) {
+                if (!isDocSetterMethodCall(node)) {
+                    return;
+                }
+                // Check if the first argument is an object literal
+                const firstArg = node.arguments[0];
+                if (firstArg?.type !== utils_1.AST_NODE_TYPES.ObjectExpression ||
+                    !hasNestedObjects(firstArg)) {
+                    return;
+                }
+                // Report and fix the issue
+                context.report({
+                    node: firstArg,
+                    messageId: 'enforceFieldPathSyntax',
+                    fix(fixer) {
+                        const newText = convertToFieldPathSyntax(firstArg, context.getSourceCode());
+                        return fixer.replaceText(firstArg, newText);
+                    },
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=enforce-fieldpath-syntax-in-docsetter.js.map