@blumintinc/eslint-plugin-blumint 1.16.2 → 1.17.0

package/lib/rules/require-props-composition.js

@@ -0,0 +1,433 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requirePropsComposition = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const minimatch_1 = require("minimatch");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_EXCLUDED_COMPONENTS = new Set([
+    'Box',
+    'Stack',
+    'Typography',
+    'Fragment',
+    'Divider',
+    'Container',
+    'Grid',
+    'Paper',
+    'Card',
+    'CardContent',
+    'CardHeader',
+    'CardActions',
+    'List',
+    'ListItem',
+    'Table',
+    'TableBody',
+    'TableCell',
+    'TableHead',
+    'TableRow',
+    'Toolbar',
+    'AppBar',
+    'Drawer',
+    'Modal',
+    'Backdrop',
+    'Collapse',
+    'Fade',
+    'Grow',
+    'Slide',
+    'Zoom',
+    'CircularProgress',
+    'LinearProgress',
+    'Skeleton',
+    'Suspense',
+    'StrictMode',
+    'Profiler',
+    'ErrorBoundary',
+    'React.Fragment',
+    'React.Suspense',
+    'React.StrictMode',
+]);
+const DEFAULT_TARGET_PATHS = ['src/components/**/*.tsx'];
+/**
+ * Derives the expected Props type name for a JSX element name.
+ * e.g. "LoadingButton" → "LoadingButtonProps"
+ */
+function toPropsTypeName(componentName) {
+    return `${componentName}Props`;
+}
+/**
+ * Returns true if the given TSTypeReference node references XProps via Pick or
+ * Omit (including nested inside Readonly<...>).
+ */
+function typeReferenceContainsPickOrOmit(node, propsTypeName) {
+    const name = getTypeReferenceName(node);
+    if (name === 'Pick' || name === 'Omit') {
+        // First type argument should be the target props type
+        const params = node.typeParameters?.params;
+        if (params && params.length >= 1) {
+            const firstParam = params[0];
+            if (firstParam.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+                const refName = getTypeReferenceName(firstParam);
+                if (refName === propsTypeName) {
+                    return true;
+                }
+            }
+        }
+    }
+    if (name === 'Readonly') {
+        // Unwrap Readonly<...> and recurse
+        const params = node.typeParameters?.params;
+        if (params && params.length === 1) {
+            const inner = params[0];
+            if (inner.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+                return typeReferenceContainsPickOrOmit(inner, propsTypeName);
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Returns the identifier name of a TSTypeReference node.
+ */
+function getTypeReferenceName(node) {
+    const typeName = node.typeName;
+    if (typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return typeName.name;
+    }
+    if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+        // e.g. React.Fragment
+        return `${typeName.left.type === utils_1.AST_NODE_TYPES.Identifier ? typeName.left.name : ''}.${typeName.right.name}`;
+    }
+    return '';
+}
+/**
+ * Recursively check if a TS type node composes with the given propsTypeName
+ * via Pick/Omit (at any level of intersection / Readonly wrapping, or nested
+ * in a TSTypeLiteral property's type annotation).
+ */
+function typeNodeComposesWithProps(typeNode, propsTypeName) {
+    switch (typeNode.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeReference: {
+            if (typeReferenceContainsPickOrOmit(typeNode, propsTypeName)) {
+                return true;
+            }
+            // Also recurse into type params (e.g. Readonly<Pick<XProps, ...>>)
+            if (typeNode.typeParameters) {
+                for (const param of typeNode.typeParameters.params) {
+                    if (typeNodeComposesWithProps(param, propsTypeName)) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        }
+        case utils_1.AST_NODE_TYPES.TSIntersectionType: {
+            // Check each member of an intersection (A & B & C)
+            return typeNode.types.some((t) => typeNodeComposesWithProps(t, propsTypeName));
+        }
+        case utils_1.AST_NODE_TYPES.TSUnionType: {
+            // Check each member of a union — for union types, at least one member composes
+            return typeNode.types.some((t) => typeNodeComposesWithProps(t, propsTypeName));
+        }
+        case utils_1.AST_NODE_TYPES.TSTypeLiteral: {
+            // Check property signatures for nested composition
+            // e.g. { iconProps?: Omit<GradientIconButtonProps, 'IconComponent'> }
+            return typeNode.members.some((member) => {
+                if (member.type === utils_1.AST_NODE_TYPES.TSPropertySignature &&
+                    member.typeAnnotation) {
+                    return typeNodeComposesWithProps(member.typeAnnotation.typeAnnotation, propsTypeName);
+                }
+                return false;
+            });
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * Collect all capitalized JSX element names used in a component's function
+ * body (handles all JSX regardless of nesting depth / conditional branches).
+ */
+function collectJsxElementNames(node) {
+    const names = new Set();
+    function visit(n) {
+        if (!n || typeof n !== 'object')
+            return;
+        if (n.type === utils_1.AST_NODE_TYPES.JSXOpeningElement &&
+            n.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier) {
+            const name = n.name.name;
+            // Only custom components — starts with uppercase
+            if (/^[A-Z]/.test(name)) {
+                names.add(name);
+            }
+        }
+        // Traverse all child nodes
+        for (const key of Object.keys(n)) {
+            if (key === 'parent')
+                continue;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const child = n[key];
+            if (Array.isArray(child)) {
+                for (const item of child) {
+                    if (item && typeof item === 'object' && 'type' in item) {
+                        visit(item);
+                    }
+                }
+            }
+            else if (child && typeof child === 'object' && 'type' in child) {
+                visit(child);
+            }
+        }
+    }
+    visit(node);
+    return names;
+}
+/**
+ * Find the Props type alias node that corresponds to a component by name.
+ * Looks for `type <ComponentName>Props = ...` in the program body.
+ */
+function findPropsTypeAlias(program, componentName) {
+    const expectedTypeName = toPropsTypeName(componentName);
+    for (const stmt of program.body) {
+        // type XProps = ...
+        if (stmt.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+            stmt.id.name === expectedTypeName) {
+            return stmt;
+        }
+        // export type XProps = ...
+        if (stmt.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+            stmt.declaration?.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+            stmt.declaration.id.name === expectedTypeName) {
+            return stmt.declaration;
+        }
+    }
+    return null;
+}
+/**
+ * Given a component function node, find the props parameter type annotation
+ * and return the type alias name if it points to one. This handles patterns
+ * like `const Foo = ({ a }: FooProps) => ...`.
+ */
+function getPropsTypeNameFromParam(funcNode) {
+    const firstParam = funcNode.params[0];
+    if (!firstParam)
+        return null;
+    let typeAnnotation = null;
+    if (firstParam.type === utils_1.AST_NODE_TYPES.Identifier &&
+        firstParam.typeAnnotation) {
+        typeAnnotation = firstParam.typeAnnotation.typeAnnotation;
+    }
+    else if (firstParam.type === utils_1.AST_NODE_TYPES.ObjectPattern &&
+        firstParam.typeAnnotation) {
+        typeAnnotation = firstParam.typeAnnotation.typeAnnotation;
+    }
+    else if (firstParam.type === utils_1.AST_NODE_TYPES.RestElement) {
+        return null;
+    }
+    if (typeAnnotation &&
+        typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+        const name = getTypeReferenceName(typeAnnotation);
+        // Strip Readonly wrapper if present
+        if (name === 'Readonly' && typeAnnotation.typeParameters?.params[0]) {
+            const inner = typeAnnotation.typeParameters.params[0];
+            if (inner.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+                return getTypeReferenceName(inner);
+            }
+        }
+        return name;
+    }
+    return null;
+}
+exports.requirePropsComposition = (0, createRule_1.createRule)({
+    name: 'require-props-composition',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require React component Props types to compose (via Pick/Omit) with the props types of non-leaf child components rendered in JSX',
+            recommended: 'warn',
+        },
+        fixable: undefined,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    targetPaths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    excludeComponents: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    minDependencyCount: {
+                        type: 'number',
+                        minimum: 1,
+                    },
+                    requireAllDependencies: {
+                        type: 'boolean',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missingPropsComposition: "Component '{{componentName}}' renders {{dependencyList}} but '{{propsTypeName}}' does not compose with {{missingList}} via Pick<...> or Omit<...>. Consider: type {{propsTypeName}} = Omit<{{primaryDep}}, 'overriddenProp'> & { /* your props */ };",
+        },
+    },
+    defaultOptions: [{}],
+    create(context, [options]) {
+        const targetPaths = options?.targetPaths ?? DEFAULT_TARGET_PATHS;
+        const excludeComponents = new Set([
+            ...DEFAULT_EXCLUDED_COMPONENTS,
+            ...(options?.excludeComponents ?? []),
+        ]);
+        const minDependencyCount = options?.minDependencyCount ?? 1;
+        const requireAllDependencies = options?.requireAllDependencies ?? false;
+        // Check whether the current file matches any of the targetPaths globs.
+        const filename = context.getFilename();
+        const matchesTargetPath = targetPaths.some((pattern) => (0, minimatch_1.minimatch)(filename, pattern, { matchBase: false }));
+        if (!matchesTargetPath) {
+            return {};
+        }
+        return {
+            // Arrow function component: const MyComponent = (...) => ...
+            VariableDeclaration(node) {
+                for (const declarator of node.declarations) {
+                    if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                        !declarator.init) {
+                        continue;
+                    }
+                    const componentName = declarator.id.name;
+                    // Must start with uppercase to be a component
+                    if (!/^[A-Z]/.test(componentName))
+                        continue;
+                    let funcNode = null;
+                    if (declarator.init.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                        declarator.init.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+                        funcNode = declarator.init;
+                    }
+                    else if (
+                    // memo((...) => ...)
+                    declarator.init.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                        const call = declarator.init;
+                        const arg0 = call.arguments[0];
+                        if (arg0 &&
+                            (arg0.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                                arg0.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
+                            funcNode = arg0;
+                        }
+                    }
+                    if (!funcNode)
+                        continue;
+                    // Get the program node from the ancestors
+                    const ancestors = context.getAncestors();
+                    const prog = ancestors[0];
+                    checkComponentWithProgram(componentName, funcNode, declarator.id, prog);
+                }
+            },
+            // Function declaration component: function MyComponent(...) { ... }
+            FunctionDeclaration(node) {
+                if (!node.id || !/^[A-Z]/.test(node.id.name))
+                    return;
+                const componentName = node.id.name;
+                const ancestors = context.getAncestors();
+                const prog = ancestors[0];
+                checkComponentWithProgram(componentName, node, node.id, prog);
+            },
+        };
+        function checkComponentWithProgram(componentName, funcNode, reportNode, prog) {
+            // Collect all JSX element names used in the component body
+            const body = funcNode.body ?? funcNode;
+            const allJsxNames = collectJsxElementNames(body);
+            // Filter to non-excluded custom components
+            const depComponents = Array.from(allJsxNames).filter((name) => !excludeComponents.has(name) && name !== componentName);
+            if (depComponents.length < minDependencyCount) {
+                return;
+            }
+            // Resolve the props type for this component
+            const propsTypeAlias = findPropsTypeAlias(prog, componentName);
+            let propsTypeName = null;
+            let propsTypeNode = null;
+            if (propsTypeAlias) {
+                propsTypeName = propsTypeAlias.id.name;
+                propsTypeNode = propsTypeAlias.typeAnnotation;
+            }
+            else {
+                // Fall back to inline parameter annotation
+                const paramTypeName = getPropsTypeNameFromParam(funcNode);
+                if (!paramTypeName) {
+                    // No props type at all — skip per spec
+                    return;
+                }
+                propsTypeName = paramTypeName;
+                // Try to find this type alias in the program too
+                const resolved = findPropsTypeAliasByName(prog, paramTypeName);
+                if (resolved) {
+                    propsTypeNode = resolved.typeAnnotation;
+                }
+            }
+            // No props type resolvable — skip
+            if (!propsTypeNode) {
+                return;
+            }
+            const composedWith = new Set();
+            const missingComposition = [];
+            for (const dep of depComponents) {
+                const expectedPropsType = toPropsTypeName(dep);
+                const composes = typeNodeComposesWithProps(propsTypeNode, expectedPropsType);
+                if (composes) {
+                    composedWith.add(dep);
+                }
+                else {
+                    missingComposition.push(dep);
+                }
+            }
+            if (!requireAllDependencies) {
+                // Only flag when NO dependency has composition
+                if (composedWith.size > 0) {
+                    return;
+                }
+            }
+            else {
+                // Flag when ANY dependency is missing composition
+                if (missingComposition.length === 0) {
+                    return;
+                }
+            }
+            const flaggedDeps = requireAllDependencies
+                ? missingComposition
+                : depComponents;
+            if (flaggedDeps.length === 0)
+                return;
+            context.report({
+                node: reportNode,
+                messageId: 'missingPropsComposition',
+                data: {
+                    componentName,
+                    propsTypeName: propsTypeName ?? `${componentName}Props`,
+                    dependencyList: depComponents.map((d) => `'${d}'`).join(', '),
+                    missingList: flaggedDeps
+                        .map((d) => `'${toPropsTypeName(d)}'`)
+                        .join(', '),
+                    primaryDep: toPropsTypeName(flaggedDeps[0]),
+                },
+            });
+        }
+    },
+});
+/**
+ * Find a type alias by name anywhere in the program body (exported or not).
+ */
+function findPropsTypeAliasByName(program, typeName) {
+    for (const stmt of program.body) {
+        if (stmt.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+            stmt.id.name === typeName) {
+            return stmt;
+        }
+        if (stmt.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+            stmt.declaration?.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+            stmt.declaration.id.name === typeName) {
+            return stmt.declaration;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=require-props-composition.js.map

package/lib/rules/require-server-timestamp-for-firestore-dates.d.ts

@@ -0,0 +1,9 @@
+type Options = [
+    {
+        firestoreTypePaths?: string[];
+        targetPaths?: string[];
+        ignoreTestFiles?: boolean;
+    }
+];
+export declare const requireServerTimestampForFirestoreDates: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"useServerTimestamp", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};