@blumintinc/eslint-plugin-blumint 1.16.2 → 1.17.0

package/lib/rules/prefer-utility-function-own-file.d.ts

@@ -0,0 +1,9 @@
+type Options = [
+    {
+        minStatements?: number;
+        minLines?: number;
+        ignoreClosures?: boolean;
+    }
+];
+export declare const preferUtilityFunctionOwnFile: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"extractUtility", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/prefer-utility-function-own-file.js

@@ -0,0 +1,505 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferUtilityFunctionOwnFile = void 0;
+const path = __importStar(require("path"));
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const DEFAULT_MIN_STATEMENTS = 8;
+const DEFAULT_MIN_LINES = 12;
+const DEFAULT_IGNORE_CLOSURES = true;
+/**
+ * Collects all identifiers referenced in a node body (for closure detection).
+ * Returns the set of identifier names referenced anywhere inside the node,
+ * not counting parameter names or locally-declared names.
+ */
+function collectReferencedIdentifiers(node) {
+    const refs = new Set();
+    const locals = new Set();
+    function walk(n) {
+        if (!n)
+            return;
+        switch (n.type) {
+            case utils_1.AST_NODE_TYPES.Identifier:
+                refs.add(n.name);
+                break;
+            case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+            case utils_1.AST_NODE_TYPES.FunctionExpression:
+            case utils_1.AST_NODE_TYPES.ArrowFunctionExpression: {
+                const fn = n;
+                // Record parameter names as locals
+                for (const param of fn.params) {
+                    collectPatternNames(param, locals);
+                }
+                walk(fn.body);
+                break;
+            }
+            case utils_1.AST_NODE_TYPES.VariableDeclarator: {
+                const decl = n;
+                collectPatternNames(decl.id, locals);
+                walk(decl.init);
+                break;
+            }
+            default: {
+                // Walk all child nodes
+                for (const key of Object.keys(n)) {
+                    if (key === 'parent')
+                        continue;
+                    const child = n[key];
+                    if (Array.isArray(child)) {
+                        for (const item of child) {
+                            if (item && typeof item === 'object' && 'type' in item) {
+                                walk(item);
+                            }
+                        }
+                    }
+                    else if (child && typeof child === 'object' && 'type' in child) {
+                        walk(child);
+                    }
+                }
+            }
+        }
+    }
+    walk(node);
+    // Remove purely local names from the reference set
+    for (const local of locals) {
+        refs.delete(local);
+    }
+    return refs;
+}
+/**
+ * Collects all binding names from a pattern into the given Set.
+ */
+function collectPatternNames(node, names) {
+    if (!node)
+        return;
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Identifier:
+            names.add(node.name);
+            break;
+        case utils_1.AST_NODE_TYPES.ArrayPattern:
+            for (const el of node.elements) {
+                if (el)
+                    collectPatternNames(el, names);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ObjectPattern:
+            for (const prop of node.properties) {
+                if (prop.type === utils_1.AST_NODE_TYPES.RestElement) {
+                    collectPatternNames(prop.argument, names);
+                }
+                else {
+                    collectPatternNames(prop.value, names);
+                }
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.AssignmentPattern:
+            collectPatternNames(node.left, names);
+            break;
+        case utils_1.AST_NODE_TYPES.RestElement:
+            collectPatternNames(node.argument, names);
+            break;
+        default:
+            break;
+    }
+}
+/**
+ * Returns the body node (BlockStatement or expression) of a function.
+ */
+function getFunctionBody(fn) {
+    return fn.body ?? null;
+}
+/**
+ * Counts statements inside a BlockStatement body (top level only).
+ */
+function countStatements(fn) {
+    const body = getFunctionBody(fn);
+    if (!body)
+        return 0;
+    if (body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+        return body.body.length;
+    }
+    // Arrow function with expression body — count as 1 statement
+    return 1;
+}
+/**
+ * Counts the number of source lines spanned by a function node.
+ */
+function countLines(fn) {
+    if (!fn.loc)
+        return 0;
+    return fn.loc.end.line - fn.loc.start.line + 1;
+}
+/**
+ * Returns the function expression node if the VariableDeclarator initializer
+ * is (unwrapped) an arrow or function expression.
+ */
+function extractFunctionInit(init) {
+    if (!init)
+        return null;
+    let node = init;
+    // Unwrap TS wrappers
+    while (node &&
+        (node.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+            node.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+            node.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+            node.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+            node.type === 'ParenthesizedExpression')) {
+        node = node.expression ?? null;
+    }
+    if (!node)
+        return null;
+    if (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+        return node;
+    }
+    return null;
+}
+/**
+ * Returns true if the function returns JSX (is a React component).
+ * We check the body for any JSXElement or JSXFragment return.
+ */
+function functionReturnsJSX(fn) {
+    return ASTHelpers_1.ASTHelpers.returnsJSX(fn);
+}
+/**
+ * Returns true if the name matches the React hook naming convention.
+ */
+function isHookName(name) {
+    return /^use[A-Z]/.test(name);
+}
+/**
+ * Extracts the basename (without extension) from a filename.
+ * E.g. "modifyRoleMembers.f.ts" → "modifyRoleMembers"
+ */
+function fileBasename(filename) {
+    const base = path.basename(filename);
+    // Strip all extensions (e.g. .f.ts, .test.ts)
+    return base.replace(/(\.\w+)+$/, '');
+}
+/**
+ * Returns true if the file should be exempt from this rule.
+ * Exempt: test/spec files, __mocks__ directories, type-only files under types/**
+ */
+function isExemptFile(filename) {
+    if (!filename)
+        return false;
+    const normalized = filename.replace(/\\/g, '/');
+    // Test and spec files
+    if (/\.(test|spec)\.(tsx?|jsx?)$/.test(normalized))
+        return true;
+    // Files inside __mocks__ directories
+    if (/\/__mocks__\//.test(normalized))
+        return true;
+    // Type files (functions/src/types/**)
+    if (/\/types\//.test(normalized))
+        return true;
+    return false;
+}
+exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
+    name: 'prefer-utility-function-own-file',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce that sizable utility functions live in their own file rather than being co-located inside an entry-point or consumer file',
+            recommended: 'warn',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    minStatements: {
+                        type: 'number',
+                        minimum: 1,
+                        default: DEFAULT_MIN_STATEMENTS,
+                    },
+                    minLines: {
+                        type: 'number',
+                        minimum: 1,
+                        default: DEFAULT_MIN_LINES,
+                    },
+                    ignoreClosures: {
+                        type: 'boolean',
+                        default: DEFAULT_IGNORE_CLOSURES,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            extractUtility: '"{{name}}" is a sizable utility function co-located in a file whose primary purpose is something else. Move it to its own file (e.g. under util/) so it is discoverable and reusable.',
+        },
+    },
+    defaultOptions: [{}],
+    create(context, [options]) {
+        const minStatements = options.minStatements ?? DEFAULT_MIN_STATEMENTS;
+        const minLines = options.minLines ?? DEFAULT_MIN_LINES;
+        const ignoreClosures = options.ignoreClosures ?? DEFAULT_IGNORE_CLOSURES;
+        const filename = context.getFilename();
+        // Exempt test/mock/type files entirely
+        if (isExemptFile(filename))
+            return {};
+        const basename = fileBasename(filename);
+        const topLevelFunctions = [];
+        let hasExportDefault = false;
+        // Names that appear as the handler inside `export default someWrapper(name)`
+        const wrappedDefaultHandlerNames = new Set();
+        // Names directly exported as default (export default myFunc style via ExportDefaultDeclaration referencing an identifier)
+        const defaultExportedIdentifiers = new Set();
+        // Names exported via `export { foo, bar }` specifiers
+        const specifierExportedNames = new Set();
+        return {
+            // Collect export default declarations
+            ExportDefaultDeclaration(node) {
+                hasExportDefault = true;
+                const decl = node.declaration;
+                // export default myFunc
+                if (decl.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    defaultExportedIdentifiers.add(decl.name);
+                }
+                // export default onCall(authenticatedOnly(myFunc))
+                if (decl.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                    // walk the call expression tree for identifier references
+                    const findWrappedIds = (expr) => {
+                        let e = expr;
+                        while (e &&
+                            (e.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+                                e.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+                                e.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+                                e.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+                                e.type === 'ParenthesizedExpression')) {
+                            e = e.expression;
+                        }
+                        if (!e)
+                            return;
+                        if (e.type === utils_1.AST_NODE_TYPES.Identifier) {
+                            wrappedDefaultHandlerNames.add(e.name);
+                        }
+                        if (e.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                            for (const arg of e.arguments) {
+                                findWrappedIds(arg);
+                            }
+                        }
+                    };
+                    findWrappedIds(decl);
+                }
+            },
+            // Collect names exported via specifiers: `export { foo, bar }`
+            ExportNamedDeclaration(node) {
+                // Only handle specifier-style exports (not `export const foo = ...` which
+                // is handled by VariableDeclaration with ExportNamedDeclaration parent)
+                if (node.declaration)
+                    return;
+                for (const specifier of node.specifiers) {
+                    if (specifier.local.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        specifierExportedNames.add(specifier.local.name);
+                    }
+                }
+            },
+            // Collect top-level FunctionDeclarations
+            FunctionDeclaration(node) {
+                // Only top-level: parent must be Program or ExportNamedDeclaration or ExportDefaultDeclaration
+                const parent = node.parent;
+                const isTopLevel = parent?.type === utils_1.AST_NODE_TYPES.Program ||
+                    parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+                    parent?.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration;
+                if (!isTopLevel)
+                    return;
+                if (!node.id)
+                    return;
+                const name = node.id.name;
+                const isNamedExport = parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration;
+                const isDefaultExport = parent?.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration;
+                topLevelFunctions.push({
+                    node,
+                    name,
+                    fn: node,
+                    isDefaultExport,
+                    isNamedExport,
+                });
+            },
+            // Collect top-level arrow/function expression VariableDeclarators
+            VariableDeclaration(node) {
+                // Only top-level
+                const parent = node.parent;
+                const isTopLevel = parent?.type === utils_1.AST_NODE_TYPES.Program ||
+                    parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration;
+                if (!isTopLevel)
+                    return;
+                const isNamedExport = parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration;
+                for (const declarator of node.declarations) {
+                    if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier)
+                        continue;
+                    const name = declarator.id.name;
+                    const fn = extractFunctionInit(declarator.init);
+                    if (!fn)
+                        continue;
+                    topLevelFunctions.push({
+                        node: declarator,
+                        name,
+                        fn,
+                        isDefaultExport: false,
+                        isNamedExport,
+                    });
+                }
+            },
+            'Program:exit'() {
+                // Determine the file's primary export name (basename heuristic)
+                // e.g. "modifyRoleMembers" in "modifyRoleMembers.f.ts"
+                const primaryName = basename;
+                // Reconcile isNamedExport for functions exported via specifiers
+                // (e.g. `export { foo, bar }` when foo/bar were declared without export keyword)
+                for (const info of topLevelFunctions) {
+                    if (!info.isNamedExport && specifierExportedNames.has(info.name)) {
+                        info.isNamedExport = true;
+                    }
+                }
+                // Determine if the file has a distinct primary export (co-location gate).
+                // A file must have SOME other purpose for us to flag anything.
+                // Indicators of a distinct primary purpose:
+                // 1. Has `export default` (callable entry-point, page, etc.)
+                // 2. Has a React component (PascalCase, returning JSX)
+                // 3. Has another named exported util that is NOT the function being evaluated
+                // We'll compute this lazily per-candidate below.
+                // If the file has no export default AND only one top-level function, the
+                // file's sole purpose IS that function — it's already in its own file.
+                // Never flag in that case.
+                const totalFunctions = topLevelFunctions.length;
+                if (!hasExportDefault && totalFunctions <= 1)
+                    return;
+                // For each candidate, determine whether to flag
+                for (const info of topLevelFunctions) {
+                    const { node, name, fn, isDefaultExport } = info;
+                    // --- Exclusion: is a hook ---
+                    if (isHookName(name))
+                        continue;
+                    // --- Exclusion: returns JSX (React component) ---
+                    if (functionReturnsJSX(fn))
+                        continue;
+                    // --- Exclusion: is the default export directly ---
+                    if (isDefaultExport)
+                        continue;
+                    // --- Exclusion: name is referenced in export default (e.g. wrapped handler) ---
+                    if (wrappedDefaultHandlerNames.has(name) ||
+                        defaultExportedIdentifiers.has(name))
+                        continue;
+                    // --- Exclusion: name matches file basename (primary export heuristic) ---
+                    if (name === primaryName)
+                        continue;
+                    // --- Exclusion: it IS a named exported util but name matches basename ---
+                    // (already covered above, but be explicit)
+                    // --- Size check: must be sizable ---
+                    const stmts = countStatements(fn);
+                    const lines = countLines(fn);
+                    const isSizable = stmts >= minStatements || lines >= minLines;
+                    if (!isSizable)
+                        continue;
+                    // --- ignoreClosures: skip if the function body references module-scoped identifiers not passed as params ---
+                    if (ignoreClosures) {
+                        const closesOverModuleScope = functionClosesOverModuleScope(fn, topLevelFunctions);
+                        if (closesOverModuleScope)
+                            continue;
+                    }
+                    // --- Co-location gate: file must have a distinct primary export ---
+                    // The file has a distinct primary purpose if:
+                    // - It has export default (and it's not THIS function)
+                    // - Another top-level function returns JSX (a React component lives here)
+                    // - Another named exported function exists that is not this one
+                    const hasDistinctPrimary = determineHasDistinctPrimary(info, topLevelFunctions, hasExportDefault);
+                    if (!hasDistinctPrimary)
+                        continue;
+                    context.report({
+                        node,
+                        messageId: 'extractUtility',
+                        data: { name },
+                    });
+                }
+            },
+        };
+    },
+});
+/**
+ * Returns true if the function closes over module-scoped bindings
+ * (identifiers defined at the top level of the module) that are NOT
+ * passed as parameters, making it non-trivially extractable.
+ *
+ * We identify "module-scope" identifiers as names of other top-level
+ * declarations in the file (functions, variables) that are NOT imported.
+ * Imported names and standard globals are considered "extractable" (you'd
+ * just re-import them).
+ *
+ * Strategy: collect referenced identifiers in the body, subtract param names,
+ * then check if any remain that are names of other top-level declarations.
+ */
+function functionClosesOverModuleScope(fn, topLevelFunctions) {
+    const body = getFunctionBody(fn);
+    if (!body)
+        return false;
+    // Collect names that are parameters of this function
+    const paramNames = new Set();
+    for (const param of fn.params) {
+        collectPatternNames(param, paramNames);
+    }
+    // Collect all identifiers referenced inside the function body
+    const referencedIds = collectReferencedIdentifiers(body);
+    // Remove params (they're passed in, fine)
+    for (const param of paramNames) {
+        referencedIds.delete(param);
+    }
+    // Get the set of top-level sibling function names
+    const topLevelNames = new Set(topLevelFunctions.map((f) => f.name));
+    // If ANY referenced identifier is a top-level sibling function name,
+    // then this function closes over a module-scope binding.
+    for (const ref of referencedIds) {
+        if (topLevelNames.has(ref)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Determines whether the file has a distinct primary purpose (co-location gate).
+ * A file has a distinct primary purpose if (excluding the function under test):
+ * - It has an `export default` declaration, OR
+ * - Another top-level function returns JSX (a component lives here), OR
+ * - Another top-level function is a named export (a different util lives here)
+ */
+function determineHasDistinctPrimary(candidate, allFunctions, hasExportDefault) {
+    // If there's an export default in the file, that signals a distinct primary
+    if (hasExportDefault)
+        return true;
+    // Check siblings for React components or other named exported utils
+    for (const other of allFunctions) {
+        if (other.name === candidate.name)
+            continue;
+        if (functionReturnsJSX(other.fn))
+            return true;
+        if (other.isNamedExport || other.isDefaultExport)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=prefer-utility-function-own-file.js.map

package/lib/rules/require-props-composition.d.ts

@@ -0,0 +1,10 @@
+type Options = [
+    {
+        targetPaths?: string[];
+        excludeComponents?: string[];
+        minDependencyCount?: number;
+        requireAllDependencies?: boolean;
+    }
+];
+export declare const requirePropsComposition: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"missingPropsComposition", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};