@blumintinc/eslint-plugin-blumint 1.20.117 → 1.20.118

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.117',
+        version: '1.20.118',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/enforce-callback-memo.js

@@ -200,6 +200,13 @@ exports.default = (0, createRule_1.createRule)({
             // that happens to build JSX, and JSX rendered from a test body are all
             // outside any render path, so wrapping there would throw
             // "Invalid hook call" while saving no re-render.
+            //
+            // The question the gate asks is RELATIVE — is a render function interposed
+            // between this attribute and whatever encloses it further out — so a
+            // component built by a plain factory (`function makeCard() { return
+            // memo(() => <X onClick={...} />); }`) reports: the arrow handed to `memo`
+            // IS the component, and `useCallback` is legal inside it no matter what
+            // the factory is called.
             if (!ASTHelpers_1.ASTHelpers.isInsideComponentOrHook(node, context)) {
                 return;
             }

package/lib/rules/enforce-firestore-set-merge.js

@@ -221,7 +221,7 @@ function initializesFirestore(declarator) {
  * deeper, inside an `ExportNamedDeclaration`. Reading the statement without
  * unwrapping makes the `export` keyword alone decide whether the file's
  * Firestore evidence is visible, which is not a distinction a `db` handle knows
- * anything about — `classBodiesByName()` already unwraps it for the same
+ * anything about — `resolveClassBody()` unwraps it for the same
  * "find the in-file declaration that carries the evidence" purpose.
  */
 function declaresFirestoreInstance(statement) {
@@ -285,35 +285,73 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
         const isReportSuppressed = (0, disableDirectives_1.createSuppressionChecker)(context);
         let plannedSetDocBinding = false;
         /**
-         * Top-level classes by name, so a field inherited from a superclass declared
-         * in the same file resolves to the declaration that carries its evidence.
+         * Classes declared directly in one statement container, by name — both the
+         * `class X {}` spelling and the `const X = class {}` one, each looked
+         * through its optional `export` wrapper.
+         *
+         * The memo hangs off the container rather than off the file. What a single
+         * container declares is the same answer for every call site that asks, so
+         * caching it is safe, whereas a file-wide name map is not: lexical
+         * resolution is position dependent, and one map computed for whichever site
+         * asked first would hand that site's answer to every other one.
          */
-        let topLevelClasses = null;
-        function classBodiesByName() {
-            if (topLevelClasses) {
-                return topLevelClasses;
+        const classesByContainer = new WeakMap();
+        function containerClasses(container, statements) {
+            const cached = classesByContainer.get(container);
+            if (cached) {
+                return cached;
             }
-            topLevelClasses = new Map();
-            for (const statement of sourceCode.ast.body) {
+            const classes = new Map();
+            for (const statement of statements) {
                 const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
                     statement.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration
                     ? statement.declaration
                     : statement;
                 if (declaration?.type === utils_1.AST_NODE_TYPES.ClassDeclaration &&
                     declaration.id) {
-                    topLevelClasses.set(declaration.id.name, declaration.body);
+                    classes.set(declaration.id.name, declaration.body);
                     continue;
                 }
                 if (declaration?.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
                     for (const declarator of declaration.declarations) {
                         if (declarator.id.type === utils_1.AST_NODE_TYPES.Identifier &&
                             declarator.init?.type === utils_1.AST_NODE_TYPES.ClassExpression) {
-                            topLevelClasses.set(declarator.id.name, declarator.init.body);
+                            classes.set(declarator.id.name, declarator.init.body);
                         }
                     }
                 }
             }
-            return topLevelClasses;
+            classesByContainer.set(container, classes);
+            return classes;
+        }
+        /**
+         * The class a superclass reference names, searched from the reference
+         * outward through every enclosing statement container so the declaration
+         * that carries the field's evidence is found wherever it sits.
+         *
+         * Scanning `Program.body` alone made the `export` keyword and the depth of a
+         * declaration decide whether a base class is visible, which is not a
+         * distinction an inherited field knows anything about. This map feeds the
+         * Realtime Database carve-out, so a miss switches the exemption off and
+         * turns a call the rule cannot legally rewrite into a report — the same
+         * hole `hasFirestoreInstanceInScope` closes for the detection direction,
+         * and the two must agree. The innermost container wins, so a nested class
+         * shadowing an outer one of the same name answers for the code that sees
+         * the shadow.
+         */
+        function resolveClassBody(name, reference) {
+            let current = reference;
+            while (current) {
+                const statements = statementsOf(current);
+                if (statements) {
+                    const found = containerClasses(current, statements).get(name);
+                    if (found) {
+                        return found;
+                    }
+                }
+                current = current.parent;
+            }
+            return null;
         }
         function enclosingClassBody(node) {
             let current = node.parent;
@@ -342,7 +380,7 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
             if (superClass?.type !== utils_1.AST_NODE_TYPES.Identifier) {
                 return false;
             }
-            const superBody = classBodiesByName().get(superClass.name);
+            const superBody = resolveClassBody(superClass.name, superClass);
             return superBody ? classBindsRealtime(superBody, name, seen) : false;
         }
         function identifierBindsRealtime(identifier) {

package/lib/rules/prefer-block-comments-for-declarations.js

@@ -57,6 +57,31 @@ exports.preferBlockCommentsForDeclarations = (0, createRule_1.createRule)({
             }
             return false;
         };
+        /**
+         * Resolve the node that owns the declaration's leading comments.
+         *
+         * A leading comment sits before the first token of the whole statement, so
+         * an `export` wrapper takes ownership of it: the `export` keyword becomes
+         * the token preceding the inner declaration and `getCommentsBefore` on that
+         * declaration returns nothing. Walking out to the wrapper keeps exported
+         * declarations — the public API this rule exists to document — in scope.
+         *
+         * Only the visitors for the inner declaration types are registered, so
+         * unwrapping here reports each declaration once; registering the export
+         * node types as extra visitors instead would report the same comment twice.
+         */
+        const resolveCommentAnchor = (node) => {
+            let anchor = node;
+            let parent = anchor.parent;
+            while (parent &&
+                (parent.type === 'ExportNamedDeclaration' ||
+                    parent.type === 'ExportDefaultDeclaration') &&
+                parent.declaration === anchor) {
+                anchor = parent;
+                parent = anchor.parent;
+            }
+            return anchor;
+        };
         /**
          * Process a node that might have a declaration comment
          */
@@ -66,10 +91,11 @@ exports.preferBlockCommentsForDeclarations = (0, createRule_1.createRule)({
                 return;
             }
             const sourceCode = context.sourceCode;
-            const comments = sourceCode.getCommentsBefore(node);
+            const anchor = resolveCommentAnchor(node);
+            const comments = sourceCode.getCommentsBefore(anchor);
             // Find the closest comment to the node
             const lastComment = comments[comments.length - 1];
-            if (lastComment && isLineCommentBeforeDeclaration(lastComment, node)) {
+            if (lastComment && isLineCommentBeforeDeclaration(lastComment, anchor)) {
                 const commentText = lastComment.value.trim();
                 const commentLabel = commentText || 'declaration comment';
                 context.report({

package/lib/rules/require-memo.js

@@ -43,20 +43,127 @@ const isUnmemoizedArrowFunction = (parentNode) => {
         startsWithUppercase(parentNode.id.name) &&
         !isComponentExplicitlyUnmemoized(parentNode.id.name));
 };
-const isUnmemoizedFunctionComponent = (parentNode, node) => {
-    return (node.type === 'FunctionDeclaration' &&
-        parentNode.type === 'Program' &&
-        node.id &&
-        startsWithUppercase(node.id.name) &&
-        !isComponentExplicitlyUnmemoized(node.id.name));
-};
-const isUnmemoizedExportedFunctionComponent = (parentNode, node) => {
+/**
+ * The nearest function whose body lexically contains `node`. Climbing from the
+ * parent keeps a function from being treated as its own enclosing function.
+ */
+function enclosingFunctionOf(node) {
+    let current = node.parent;
+    while (current) {
+        if (isFunction(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Return arguments belonging to `fn` itself. Descent stops at a nested
+ * function, whose returns belong to it rather than to `fn`.
+ */
+function ownReturnArguments(fn) {
+    if (fn.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+        return [fn.body];
+    }
+    const args = [];
+    const visit = (node) => {
+        if (isFunction(node)) {
+            return;
+        }
+        if (node.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
+            if (node.argument) {
+                args.push(node.argument);
+            }
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key === 'parent') {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (ASTHelpers_1.ASTHelpers.isNode(item)) {
+                        visit(item);
+                    }
+                }
+            }
+            else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                visit(value);
+            }
+        }
+    };
+    fn.body.body.forEach(visit);
+    return args;
+}
+/** Strips type-level wrappers so `return Row as ComponentType<P>` still reads as `Row`. */
+function unwrapValue(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+        node.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+        node.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+        node.type === utils_1.AST_NODE_TYPES.TSNonNullExpression) {
+        return unwrapValue(node.expression);
+    }
+    return node;
+}
+/**
+ * Whether `enclosing` is an HOC factory that hands `componentName` straight back
+ * to its callers. Such a component reaches callers as-is, so wrapping it in
+ * memo() at its declaration is the correct remedy — exactly as it is at module
+ * scope. A `memo(Row)` / `forwardRef(Row)` return is not a bare hand-back: the
+ * component is already memoized and a second wrapper would be redundant.
+ */
+function handsComponentToCallers(enclosing, componentName, context) {
+    // A function that renders JSX is a render body, not a factory. Components
+    // declared in one are recreated on every render, which memo() cannot fix;
+    // `memo-nested-react-components` owns that shape and says so in its message.
+    if (ASTHelpers_1.ASTHelpers.returnsJSX(enclosing.body, context)) {
+        return false;
+    }
+    return ownReturnArguments(enclosing).some((argument) => {
+        const value = unwrapValue(argument);
+        return (value.type === utils_1.AST_NODE_TYPES.Identifier && value.name === componentName);
+    });
+}
+/**
+ * Whether wrapping the declaration in memo() where it stands is the right fix.
+ *
+ * This is the rule's real question, and it is about the binding's lifetime, not
+ * about which node happens to be the declaration's parent: a component whose
+ * binding outlives a render (module scope — including a block, a namespace and
+ * `export default`) is memoizable in place, and so is one an HOC factory returns
+ * unwrapped. A component created inside a render body is not; it gets a fresh
+ * identity on every render and `memo-nested-react-components` owns it.
+ */
+function isMemoizableInPlace(node, context) {
+    const enclosing = enclosingFunctionOf(node);
+    if (!enclosing) {
+        return true;
+    }
+    return handsComponentToCallers(enclosing, node.id?.name ?? '', context);
+}
+const isUnmemoizedFunctionComponent = (node, context) => {
     return (node.type === 'FunctionDeclaration' &&
-        parentNode.type === 'ExportNamedDeclaration' &&
-        node.id &&
+        !!node.id &&
         startsWithUppercase(node.id.name) &&
-        !isComponentExplicitlyUnmemoized(node.id.name));
+        !isComponentExplicitlyUnmemoized(node.id.name) &&
+        isMemoizableInPlace(node, context));
 };
+/**
+ * Statement positions where the rewritten `const X = memo(...)` is legal. A
+ * function declaration is also grammatical as the lone body of an `if` or a
+ * labelled statement, where a lexical declaration is not, so the report there
+ * stands without an edit.
+ */
+const CONST_HOSTING_PARENTS = new Set([
+    utils_1.AST_NODE_TYPES.Program,
+    utils_1.AST_NODE_TYPES.ExportNamedDeclaration,
+    utils_1.AST_NODE_TYPES.ExportDefaultDeclaration,
+    utils_1.AST_NODE_TYPES.BlockStatement,
+    utils_1.AST_NODE_TYPES.StaticBlock,
+    utils_1.AST_NODE_TYPES.SwitchCase,
+    utils_1.AST_NODE_TYPES.TSModuleBlock,
+]);
+const canHostConstDeclaration = (parentNode) => CONST_HOSTING_PARENTS.has(parentNode.type);
 const MEMO_NAME = 'memo';
 function isMemoImport(importPath) {
     // Match both absolute and relative paths ending with util/memo
@@ -146,12 +253,9 @@ function checkFunction(context, node) {
     }
     if (ASTHelpers_1.ASTHelpers.returnsJSX(node.body, context) &&
         ASTHelpers_1.ASTHelpers.hasParameters(node)) {
-        const results = [
-            isUnmemoizedArrowFunction,
-            isUnmemoizedFunctionComponent,
-            isUnmemoizedExportedFunctionComponent,
-        ].map((fn) => fn(parentNode, node));
-        if (results.some((result) => !!result)) {
+        const isDeclarationComponent = isUnmemoizedFunctionComponent(node, context);
+        const isArrowComponent = isUnmemoizedArrowFunction(parentNode);
+        if (isDeclarationComponent || isArrowComponent) {
             const componentName = (node.type === 'FunctionDeclaration' && node.id?.name) ||
                 (parentNode.type === 'VariableDeclarator' &&
                     parentNode.id.type === 'Identifier' &&
@@ -163,7 +267,7 @@ function checkFunction(context, node) {
                 data: {
                     name: componentName,
                 },
-                fix: results[2] || results[1]
+                fix: isDeclarationComponent && canHostConstDeclaration(parentNode)
                     ? function fix(fixer) {
                         if (node.async || node.generator) {
                             return null;
@@ -211,11 +315,23 @@ function checkFunction(context, node) {
                         const functionKeywordReplacement = `const ${node.id.name} = memo(`;
                         // Step 3: Rename function
                         const functionNameReplacement = `function ${node.id.name}Unmemoized`;
+                        // `export default const X = memo(...)` is a syntax error, so a
+                        // default-exported declaration becomes a memoized const plus a
+                        // trailing `export default X;`. The local binding is preserved
+                        // because other statements in the module may reference it.
+                        const defaultExport = parentNode.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration
+                            ? parentNode
+                            : null;
                         const fixes = [
                             fixer.replaceTextRange(functionKeywordRange, functionKeywordReplacement),
-                            fixer.insertTextAfterRange([node.range[1], node.range[1]], ');'),
+                            fixer.insertTextAfterRange([node.range[1], node.range[1]], defaultExport
+                                ? `);\nexport default ${node.id.name};`
+                                : ');'),
                             fixer.replaceTextRange([node.id.range[0] - 1, node.id.range[1]], functionNameReplacement),
                         ];
+                        if (defaultExport) {
+                            fixes.push(fixer.removeRange([defaultExport.range[0], node.range[0]]));
+                        }
                         if (importFix) {
                             fixes.push(importFix);
                         }

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

@@ -101,6 +101,36 @@ function typeReferenceContainsPickOrOmit(node, propsTypeName) {
     }
     return false;
 }
+/**
+ * The statement list a declaration can sit directly inside. A node that holds no
+ * statement list yields undefined, so a lexical walk simply steps past it.
+ */
+function statementsOf(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Program:
+        case utils_1.AST_NODE_TYPES.BlockStatement:
+        case utils_1.AST_NODE_TYPES.TSModuleBlock:
+        case utils_1.AST_NODE_TYPES.StaticBlock:
+            return node.body;
+        case utils_1.AST_NODE_TYPES.SwitchCase:
+            return node.consequent;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Look through an `export` wrapper to the declaration it carries. `export type
+ * XProps = …` and `export const X = …` are the same declaration one AST node
+ * deeper, and the `export` keyword says nothing about what the declaration
+ * declares.
+ */
+function unwrapExport(statement) {
+    if (statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+        statement.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration) {
+        return statement.declaration ?? null;
+    }
+    return statement;
+}
 /**
  * Returns the identifier name of a TSTypeReference node.
  */
@@ -121,14 +151,14 @@ function getTypeReferenceName(node) {
  * named-alias indirection, or nested in a TSTypeLiteral property's type
  * annotation).
  *
- * `program` (when supplied) enables resolving a locally-declared named type
- * alias to its definition, so composition can be seen through named union arms
- * and shared bases. `seenAliases` guards against recursive-alias cycles; each
- * descent *through* an alias extends a copy of the set so that sibling paths
- * (e.g. two union arms sharing a base) each resolve the shared alias
- * independently.
+ * `scope` (when supplied) is the node the alias lookup walks outward from, which
+ * enables resolving a locally-declared named type alias to its definition, so
+ * composition can be seen through named union arms and shared bases.
+ * `seenAliases` guards against recursive-alias cycles; each descent *through* an
+ * alias extends a copy of the set so that sibling paths (e.g. two union arms
+ * sharing a base) each resolve the shared alias independently.
  */
-function typeNodeComposesWithProps(typeNode, propsTypeName, program, seenAliases = new Set()) {
+function typeNodeComposesWithProps(typeNode, propsTypeName, scope, seenAliases = new Set()) {
     switch (typeNode.type) {
         case utils_1.AST_NODE_TYPES.TSTypeReference: {
             // A direct reference to the child's whole props type (bare `ChildProps`
@@ -144,7 +174,7 @@ function typeNodeComposesWithProps(typeNode, propsTypeName, program, seenAliases
             // Also recurse into type params (e.g. Readonly<Pick<XProps, ...>>)
             if (typeNode.typeParameters) {
                 for (const param of typeNode.typeParameters.params) {
-                    if (typeNodeComposesWithProps(param, propsTypeName, program, seenAliases)) {
+                    if (typeNodeComposesWithProps(param, propsTypeName, scope, seenAliases)) {
                         return true;
                     }
                 }
@@ -154,14 +184,14 @@ function typeNodeComposesWithProps(typeNode, propsTypeName, program, seenAliases
             // shared bases (issue #1343): `RowActionableProps` → `RowBaseProps & {…}`
             // → `Pick<MenuItemProps, …>`. Only in-file aliases resolve; imported
             // names (e.g. MenuItemProps) return null and are left as-is.
-            if (program) {
+            if (scope) {
                 const aliasName = getTypeReferenceName(typeNode);
                 if (aliasName && !seenAliases.has(aliasName)) {
-                    const alias = findPropsTypeAliasByName(program, aliasName);
+                    const alias = findPropsTypeAliasByName(scope, aliasName);
                     if (alias) {
                         const nextSeen = new Set(seenAliases);
                         nextSeen.add(aliasName);
-                        if (typeNodeComposesWithProps(alias.typeAnnotation, propsTypeName, program, nextSeen)) {
+                        if (typeNodeComposesWithProps(alias.typeAnnotation, propsTypeName, scope, nextSeen)) {
                             return true;
                         }
                     }
@@ -172,7 +202,7 @@ function typeNodeComposesWithProps(typeNode, propsTypeName, program, seenAliases
         case utils_1.AST_NODE_TYPES.TSIntersectionType: {
             // Check each member of an intersection (A & B & C) — the whole
             // intersection composes if any member does.
-            return typeNode.types.some((t) => typeNodeComposesWithProps(t, propsTypeName, program, seenAliases));
+            return typeNode.types.some((t) => typeNodeComposesWithProps(t, propsTypeName, scope, seenAliases));
         }
         case utils_1.AST_NODE_TYPES.TSUnionType: {
             // A union (A | B) composes if ANY arm composes. `.some` (not `.every`) is
@@ -182,7 +212,7 @@ function typeNodeComposesWithProps(typeNode, propsTypeName, program, seenAliases
             // every rendered child would flag that legitimate pattern — a false
             // positive the repo prefers to avoid. `.some` still passes the target
             // case, where every arm composes with the single shared child.
-            return typeNode.types.some((t) => typeNodeComposesWithProps(t, propsTypeName, program, seenAliases));
+            return typeNode.types.some((t) => typeNodeComposesWithProps(t, propsTypeName, scope, seenAliases));
         }
         case utils_1.AST_NODE_TYPES.TSTypeLiteral: {
             // Check property signatures for nested composition
@@ -190,7 +220,7 @@ function typeNodeComposesWithProps(typeNode, propsTypeName, program, seenAliases
             return typeNode.members.some((member) => {
                 if (member.type === utils_1.AST_NODE_TYPES.TSPropertySignature &&
                     member.typeAnnotation) {
-                    return typeNodeComposesWithProps(member.typeAnnotation.typeAnnotation, propsTypeName, program, seenAliases);
+                    return typeNodeComposesWithProps(member.typeAnnotation.typeAnnotation, propsTypeName, scope, seenAliases);
                 }
                 return false;
             });
@@ -321,24 +351,10 @@ function collectPropSlotNames(funcNode) {
 }
 /**
  * Find the Props type alias node that corresponds to a component by name.
- * Looks for `type <ComponentName>Props = ...` in the program body.
+ * Looks for `type <ComponentName>Props = ...` in `scope`'s lexical chain.
  */
-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;
+function findPropsTypeAlias(scope, componentName) {
+    return findPropsTypeAliasByName(scope, toPropsTypeName(componentName));
 }
 /**
  * Given a component function node, find the props parameter type annotation
@@ -416,58 +432,92 @@ function isPropsPreservingHocCallee(callee) {
         callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
         PROPS_PRESERVING_HOCS.has(callee.property.name));
 }
-/**
- * Resolve the function node for a component name in the program, following a
- * single-identifier alias (`const Live = LiveUnmemoized`) and unwrapping a HOC
- * call (`memo((props) => ...)`). Returns null when no function is found.
- */
-function findComponentFunction(program, name, lookup = {}) {
-    const seen = lookup.seen ?? new Set();
-    const nextLookup = { ...lookup, seen };
-    if (seen.has(name))
-        return null;
-    seen.add(name);
-    for (const stmt of program.body) {
-        const decl = stmt.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration
-            ? stmt.declaration
-            : stmt;
+const UNPROVABLE = { fn: null };
+function findComponentFunctionInStatements(statements, name, lookup, nextLookup) {
+    for (const stmt of statements) {
+        const decl = unwrapExport(stmt);
         if (!decl)
             continue;
-        if (decl.type === utils_1.AST_NODE_TYPES.FunctionDeclaration &&
+        if ((decl.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+            decl.type === utils_1.AST_NODE_TYPES.ClassDeclaration) &&
             decl.id?.name === name) {
-            return decl;
+            // A class component binds the name without being a ComponentFunction, so
+            // it proves nothing and still ends the search.
+            return decl.type === utils_1.AST_NODE_TYPES.FunctionDeclaration
+                ? { fn: decl }
+                : UNPROVABLE;
         }
         if (decl.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
             for (const declarator of decl.declarations) {
                 if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
-                    declarator.id.name !== name ||
-                    !declarator.init) {
+                    declarator.id.name !== name) {
                     continue;
                 }
                 const init = declarator.init;
+                if (!init) {
+                    return UNPROVABLE;
+                }
                 if (init.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
                     init.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
-                    return init;
+                    return { fn: init };
                 }
                 if (init.type === utils_1.AST_NODE_TYPES.CallExpression) {
                     if (lookup.propsPreservingHocsOnly &&
                         !isPropsPreservingHocCallee(init.callee)) {
                         // The binding IS this call, and the call is not known to preserve
                         // props — so nothing about its props surface is provable.
-                        return null;
+                        return UNPROVABLE;
                     }
                     const arg0 = init.arguments[0];
                     if (arg0 &&
                         (arg0.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
                             arg0.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
-                        return arg0;
+                        return { fn: arg0 };
                     }
+                    return UNPROVABLE;
                 }
                 if (init.type === utils_1.AST_NODE_TYPES.Identifier) {
-                    return findComponentFunction(program, init.name, nextLookup);
+                    // The alias target is resolved from the alias's own declaration site,
+                    // which is the scope the alias was written in — not the site that
+                    // asked, which may sit several containers deeper.
+                    return {
+                        fn: findComponentFunction(declarator, init.name, nextLookup),
+                    };
                 }
+                return UNPROVABLE;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the function node a component name binds to, following a
+ * single-identifier alias (`const Live = LiveUnmemoized`) and unwrapping a HOC
+ * call (`memo((props) => ...)`). Returns null when no function is found.
+ *
+ * The search runs from `scope` outward through every enclosing statement
+ * container, so a child declared beside the JSX that renders it resolves exactly
+ * as a top-level one does. Anchoring at `Program.body` made a nested
+ * `const Spinner = memo(() => <div />)` unresolvable, and an unresolvable child
+ * is treated as one that takes props: the rule then demanded a `SpinnerProps`
+ * that cannot exist, because Spinner declares no parameters (issue #1776).
+ */
+function findComponentFunction(scope, name, lookup = {}) {
+    const seen = lookup.seen ?? new Set();
+    const nextLookup = { ...lookup, seen };
+    if (seen.has(name))
+        return null;
+    seen.add(name);
+    let current = scope;
+    while (current) {
+        const statements = statementsOf(current);
+        if (statements) {
+            const resolved = findComponentFunctionInStatements(statements, name, lookup, nextLookup);
+            if (resolved) {
+                return resolved.fn;
             }
         }
+        current = current.parent;
     }
     return null;
 }
@@ -476,9 +526,15 @@ function findComponentFunction(program, name, lookup = {}) {
  * parameters has no props surface to compose with, so it is not a composition
  * dependency (same category as a decorative icon). Only in-file resolution is
  * used; imported children are left to the normal composition check.
+ *
+ * `scope` must be anchored at the JSX site's own container rather than at the
+ * program: a child declared inside the very component that renders it is the
+ * commonplace shape (`memo-nested-react-components` ships as an error, which
+ * presumes nested components exist), and reading its unresolvability as "takes
+ * props" names a props type the author cannot write.
  */
-function isZeroPropComponent(program, name) {
-    const fn = findComponentFunction(program, name, {
+function isZeroPropComponent(scope, name) {
+    const fn = findComponentFunction(scope, name, {
         propsPreservingHocsOnly: true,
     });
     return fn !== null && fn.params.length === 0;
@@ -892,12 +948,12 @@ function isPropLessImportedComponent(program, localName, filename, componentRoot
  * first-parameter type annotation. Used to detect inverse composition, where
  * the child derives its props from the parent's props type.
  */
-function getDependencyPropsSourceType(program, depName) {
-    const alias = findPropsTypeAliasByName(program, toPropsTypeName(depName));
+function getDependencyPropsSourceType(scope, depName) {
+    const alias = findPropsTypeAliasByName(scope, toPropsTypeName(depName));
     if (alias) {
         return alias.typeAnnotation;
     }
-    const fn = findComponentFunction(program, depName);
+    const fn = findComponentFunction(scope, depName);
     if (fn) {
         return getFirstParamTypeNode(fn);
     }
@@ -912,10 +968,10 @@ function getDependencyPropsSourceType(program, depName) {
  * followed to its definition too, because an alias of a union flattens into the
  * enclosing union in TypeScript, so its own arms are arms here.
  */
-function collectUnionArmNames(arm, program, seenAliases, into) {
+function collectUnionArmNames(arm, scope, seenAliases, into) {
     if (arm.type === utils_1.AST_NODE_TYPES.TSUnionType) {
         for (const nested of arm.types) {
-            collectUnionArmNames(nested, program, seenAliases, into);
+            collectUnionArmNames(nested, scope, seenAliases, into);
         }
         return;
     }
@@ -927,7 +983,7 @@ function collectUnionArmNames(arm, program, seenAliases, into) {
         // A `Readonly<X>` arm is the X arm: the wrapper adds no surface of its own.
         const inner = arm.typeParameters?.params[0];
         if (inner) {
-            collectUnionArmNames(inner, program, seenAliases, into);
+            collectUnionArmNames(inner, scope, seenAliases, into);
         }
         return;
     }
@@ -935,11 +991,11 @@ function collectUnionArmNames(arm, program, seenAliases, into) {
         return;
     }
     into.add(name);
-    const alias = findPropsTypeAliasByName(program, name);
+    const alias = findPropsTypeAliasByName(scope, name);
     if (alias) {
         const nextSeen = new Set(seenAliases);
         nextSeen.add(name);
-        collectUnionArmNames(alias.typeAnnotation, program, nextSeen, into);
+        collectUnionArmNames(alias.typeAnnotation, scope, nextSeen, into);
     }
 }
 /**
@@ -952,13 +1008,13 @@ function collectUnionArmNames(arm, program, seenAliases, into) {
  * real union is a member, so an alias chain that ends at a single object type
  * credits none of the names it passed through.
  */
-function collectUnionMemberNames(typeNode, program, seenAliases = new Set(), into = new Set()) {
+function collectUnionMemberNames(typeNode, scope, seenAliases = new Set(), into = new Set()) {
     if (!typeNode) {
         return into;
     }
     if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType) {
         for (const arm of typeNode.types) {
-            collectUnionArmNames(arm, program, seenAliases, into);
+            collectUnionArmNames(arm, scope, seenAliases, into);
         }
         return into;
     }
@@ -967,16 +1023,16 @@ function collectUnionMemberNames(typeNode, program, seenAliases = new Set(), int
         if (name === 'Readonly') {
             const inner = typeNode.typeParameters?.params[0];
             if (inner) {
-                collectUnionMemberNames(inner, program, seenAliases, into);
+                collectUnionMemberNames(inner, scope, seenAliases, into);
             }
             return into;
         }
         if (name && !seenAliases.has(name)) {
-            const alias = findPropsTypeAliasByName(program, name);
+            const alias = findPropsTypeAliasByName(scope, name);
             if (alias) {
                 const nextSeen = new Set(seenAliases);
                 nextSeen.add(name);
-                collectUnionMemberNames(alias.typeAnnotation, program, nextSeen, into);
+                collectUnionMemberNames(alias.typeAnnotation, scope, nextSeen, into);
             }
         }
     }
@@ -1192,33 +1248,47 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
          *
          * A dependency whose props type is not a union yields no members, so this
          * never credits a parent that composes with nothing.
+         *
+         * `scope` resolves in-file declarations lexically, while `prog` answers the
+         * questions that are genuinely module-level: an import can only ever appear
+         * at the top of the file, so its spelling does not depend on where the JSX
+         * sits.
          */
-        function composesWithUnionMember(dep, propsTypeNode, prog, componentRoot) {
-            const localMembers = collectUnionMemberNames(getDependencyPropsSourceType(prog, dep), prog);
+        function composesWithUnionMember(dep, propsTypeNode, prog, scope, componentRoot) {
+            const localMembers = collectUnionMemberNames(getDependencyPropsSourceType(scope, dep), scope);
             for (const member of localMembers) {
-                if (typeNodeComposesWithProps(propsTypeNode, member, prog)) {
+                if (typeNodeComposesWithProps(propsTypeNode, member, scope)) {
                     return true;
                 }
             }
             const importedMembers = getImportedDependencyUnionMembers(prog, dep, rawFilename, componentRoot, cwd);
-            return importedMembers.some((member) => collectImportSpellings(prog, member).some((spelling) => typeNodeComposesWithProps(propsTypeNode, spelling, prog)));
+            return importedMembers.some((member) => collectImportSpellings(prog, member).some((spelling) => typeNodeComposesWithProps(propsTypeNode, spelling, scope)));
         }
         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);
             const propSlots = collectPropSlotNames(funcNode);
+            // A rendered child is resolved from the JSX site outward, so a component
+            // declared inside this very body is found; the component's own props alias
+            // is resolved from the *declaration* site outward, because a parameter
+            // annotation is read in the scope enclosing the function, never in its
+            // body. `bodyScope`'s chain contains `declarationScope`'s, so the two only
+            // differ over declarations local to the body — exactly the nested children
+            // the dependency lookups must see and the props lookups must not.
+            const bodyScope = body;
+            const declarationScope = funcNode;
             // Filter to non-excluded custom components
             const depComponents = Array.from(allJsxNames).filter((name) => !excludeComponents.has(name) &&
                 !isDecorativeIcon(name) &&
                 name !== componentName &&
                 !propSlots.has(name) &&
-                !isZeroPropComponent(prog, name));
+                !isZeroPropComponent(bodyScope, name));
             if (depComponents.length < minDependencyCount) {
                 return;
             }
             // Resolve the props type for this component
-            const propsTypeAlias = findPropsTypeAlias(prog, componentName);
+            const propsTypeAlias = findPropsTypeAlias(declarationScope, componentName);
             let propsTypeName = null;
             let propsTypeNode = null;
             if (propsTypeAlias) {
@@ -1233,8 +1303,8 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
                     return;
                 }
                 propsTypeName = paramTypeName;
-                // Try to find this type alias in the program too
-                const resolved = findPropsTypeAliasByName(prog, paramTypeName);
+                // Try to find this type alias in scope too
+                const resolved = findPropsTypeAliasByName(declarationScope, paramTypeName);
                 if (resolved) {
                     propsTypeNode = resolved.typeAnnotation;
                 }
@@ -1247,7 +1317,7 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
             const missingComposition = [];
             for (const dep of depComponents) {
                 const expectedPropsType = toPropsTypeName(dep);
-                let composes = typeNodeComposesWithProps(propsTypeNode, expectedPropsType, prog);
+                let composes = typeNodeComposesWithProps(propsTypeNode, expectedPropsType, declarationScope);
                 // Inverse composition: the child derives its props FROM this parent's
                 // props type (e.g. `Omit<ParentProps, 'children'>`, often with no named
                 // ChildProps at all). The parent is then the single shared source of
@@ -1255,9 +1325,9 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
                 // *also* compose from ChildProps would invert the source of truth or
                 // create a circular dependency.
                 if (!composes && propsTypeName) {
-                    const depPropsSource = getDependencyPropsSourceType(prog, dep);
+                    const depPropsSource = getDependencyPropsSourceType(bodyScope, dep);
                     if (depPropsSource &&
-                        typeNodeComposesWithProps(depPropsSource, propsTypeName, prog)) {
+                        typeNodeComposesWithProps(depPropsSource, propsTypeName, bodyScope)) {
                         composes = true;
                     }
                 }
@@ -1281,7 +1351,7 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
                 (requireAllDependencies || composedWith.size === 0)) {
                 for (let index = missingComposition.length - 1; index >= 0; index--) {
                     const dep = missingComposition[index];
-                    if (composesWithUnionMember(dep, propsTypeNode, prog, funcNode)) {
+                    if (composesWithUnionMember(dep, propsTypeNode, prog, bodyScope, funcNode)) {
                         composedWith.add(dep);
                         missingComposition.splice(index, 1);
                     }
@@ -1331,19 +1401,31 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
     },
 });
 /**
- * Find a type alias by name anywhere in the program body (exported or not).
+ * Find a type alias by name (exported or not), searching from `scope` outward
+ * through every enclosing statement container.
+ *
+ * Scanning `Program.body` alone made the *depth* of a declaration decide whether
+ * it exists, a distinction a props type knows nothing about: a component and its
+ * props alias written inside a factory, a `describe` block or an
+ * `export namespace` resolved to nothing, so the rule returned early and went
+ * silent (issue #1776). The innermost container wins, so an alias declared
+ * beside the component shadows a same-named one further out — a file-wide search
+ * would instead hand one scope's verdict to another.
  */
-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;
+function findPropsTypeAliasByName(scope, typeName) {
+    let current = scope;
+    while (current) {
+        const statements = statementsOf(current);
+        if (statements) {
+            for (const stmt of statements) {
+                const declaration = unwrapExport(stmt);
+                if (declaration?.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+                    declaration.id.name === typeName) {
+                    return declaration;
+                }
+            }
         }
+        current = current.parent;
     }
     return null;
 }

package/lib/utils/ASTHelpers.d.ts

@@ -69,6 +69,22 @@ export declare class ASTHelpers {
     private static readonly TRANSPARENT_WRAPPER_CALLEES;
     private static isFunctionNode;
     private static isTransparentWrapperCall;
+    /**
+     * Calls whose function argument IS a component render function. `memo`,
+     * `forwardRef` and `observer` define a component out of the callback they are
+     * handed, so that callback is a render path even with no binding to take a
+     * name from. `useCallback`/`useMemo` are deliberately absent: they wrap a
+     * value or an event handler produced inside a component, not a component.
+     */
+    private static readonly COMPONENT_DEFINING_CALLEES;
+    private static hasCalleeNamed;
+    /**
+     * Whether an anonymous function is the argument of a call that defines a
+     * component from it (`memo(() => <div />)`, `React.forwardRef((p, ref) =>
+     * ...)`). TS assertions between the function and the call are stepped over so
+     * `memo((() => <div />) as FC)` classifies the same way.
+     */
+    private static isComponentDefiningArgument;
     private static staticPropertyName;
     /**
      * Resolves the name a function is known by: its own identifier, or the
@@ -97,9 +113,20 @@ export declare class ASTHelpers {
      * that name alone — `buildTree` is not a component even though it returns
      * JSX, because the name is an explicit signal about its role. Only a truly
      * anonymous function falls back to "does it return JSX", which is what makes
-     * `memo(() => <div />)` a component. That fallback is suppressed when some
-     * enclosing function carries a non-component name, since a callback nested in
-     * a plain helper is no more of a render path than the helper itself.
+     * `memo(() => <div />)` a component.
+     *
+     * Both component spellings answer the moment they are met, walking outwards,
+     * so the question stays RELATIVE: is a render function interposed between the
+     * node and whatever encloses it further out? A component nested in a plain
+     * helper is still a component, and the hook is legal inside it — `function
+     * makeCard() { return memo(() => <X onClick={...} />); }` is a render path
+     * even though `makeCard` is not.
+     *
+     * The remaining `hasNamedNonComponent` veto only settles the case where no
+     * component was found at all. It keeps a bare callback such as
+     * `items.map((i) => <Row />)` inside a plain helper silent: that callback is
+     * anonymous and returns JSX, but nothing turns it into a component, so it is
+     * no more of a render path than the helper holding it.
      */
     static isInsideComponentOrHook(node: TSESTree.Node, context?: Readonly<TSESLint.RuleContext<string, readonly unknown[]>>): boolean;
     /**

package/lib/utils/ASTHelpers.js

@@ -744,14 +744,43 @@ class ASTHelpers {
             node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration);
     }
     static isTransparentWrapperCall(node) {
+        return this.hasCalleeNamed(node, this.TRANSPARENT_WRAPPER_CALLEES);
+    }
+    static hasCalleeNamed(node, names) {
         const { callee } = node;
         if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
-            return this.TRANSPARENT_WRAPPER_CALLEES.has(callee.name);
+            return names.has(callee.name);
         }
         return (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
             !callee.computed &&
             callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
-            this.TRANSPARENT_WRAPPER_CALLEES.has(callee.property.name));
+            names.has(callee.property.name));
+    }
+    /**
+     * Whether an anonymous function is the argument of a call that defines a
+     * component from it (`memo(() => <div />)`, `React.forwardRef((p, ref) =>
+     * ...)`). TS assertions between the function and the call are stepped over so
+     * `memo((() => <div />) as FC)` classifies the same way.
+     */
+    static isComponentDefiningArgument(node) {
+        let child = node;
+        let parent = node.parent;
+        while (parent) {
+            if (parent.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+                parent.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+                parent.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+                parent.type === utils_1.AST_NODE_TYPES.TSTypeAssertion) {
+                child = parent;
+                parent = parent.parent;
+                continue;
+            }
+            if (parent.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+                return false;
+            }
+            return (parent.arguments.includes(child) &&
+                this.hasCalleeNamed(parent, this.COMPONENT_DEFINING_CALLEES));
+        }
+        return false;
     }
     static staticPropertyName(key, computed) {
         if (computed) {
@@ -844,9 +873,20 @@ class ASTHelpers {
      * that name alone — `buildTree` is not a component even though it returns
      * JSX, because the name is an explicit signal about its role. Only a truly
      * anonymous function falls back to "does it return JSX", which is what makes
-     * `memo(() => <div />)` a component. That fallback is suppressed when some
-     * enclosing function carries a non-component name, since a callback nested in
-     * a plain helper is no more of a render path than the helper itself.
+     * `memo(() => <div />)` a component.
+     *
+     * Both component spellings answer the moment they are met, walking outwards,
+     * so the question stays RELATIVE: is a render function interposed between the
+     * node and whatever encloses it further out? A component nested in a plain
+     * helper is still a component, and the hook is legal inside it — `function
+     * makeCard() { return memo(() => <X onClick={...} />); }` is a render path
+     * even though `makeCard` is not.
+     *
+     * The remaining `hasNamedNonComponent` veto only settles the case where no
+     * component was found at all. It keeps a bare callback such as
+     * `items.map((i) => <Row />)` inside a plain helper silent: that callback is
+     * anonymous and returns JSX, but nothing turns it into a component, so it is
+     * no more of a render path than the helper holding it.
      */
     static isInsideComponentOrHook(node, context) {
         const anonymousFunctions = [];
@@ -856,6 +896,10 @@ class ASTHelpers {
             if (this.isFunctionNode(current)) {
                 const name = this.inferFunctionName(current);
                 if (name === null) {
+                    if (this.isComponentDefiningArgument(current) &&
+                        this.returnsJSX(current, context)) {
+                        return true;
+                    }
                     anonymousFunctions.push(current);
                 }
                 else if (this.isComponentOrHookName(name)) {
@@ -894,5 +938,17 @@ ASTHelpers.TRANSPARENT_WRAPPER_CALLEES = new Set([
     'useCallback',
     'useMemo',
 ]);
+/**
+ * Calls whose function argument IS a component render function. `memo`,
+ * `forwardRef` and `observer` define a component out of the callback they are
+ * handed, so that callback is a render path even with no binding to take a
+ * name from. `useCallback`/`useMemo` are deliberately absent: they wrap a
+ * value or an event handler produced inside a component, not a component.
+ */
+ASTHelpers.COMPONENT_DEFINING_CALLEES = new Set([
+    'forwardRef',
+    'memo',
+    'observer',
+]);
 exports.ASTHelpers = ASTHelpers;
 //# sourceMappingURL=ASTHelpers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.117",
+  "version": "1.20.118",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,50 @@
 [
+  {
+    "version": "1.20.118",
+    "date": "2026-08-06T03:08:14.815Z",
+    "rules": [
+      {
+        "name": "enforce-callback-memo",
+        "changeType": "fix",
+        "issues": [
+          1777
+        ],
+        "summary": "answer the anonymous component where it is met (closes #1777)"
+      },
+      {
+        "name": "enforce-firestore-set-merge",
+        "changeType": "fix",
+        "issues": [
+          1773
+        ],
+        "summary": "resolve the base class lexically too (closes #1773)"
+      },
+      {
+        "name": "prefer-block-comments-for-declarations",
+        "changeType": "fix",
+        "issues": [
+          1775
+        ],
+        "summary": "anchor the comment lookup on the export wrapper (closes #1775)"
+      },
+      {
+        "name": "require-memo",
+        "changeType": "fix",
+        "issues": [
+          1774
+        ],
+        "summary": "claim a component by lifetime, not by parent node type (closes #1774)"
+      },
+      {
+        "name": "require-props-composition",
+        "changeType": "fix",
+        "issues": [
+          1776
+        ],
+        "summary": "resolve names lexically in both directions (closes #1776)"
+      }
+    ]
+  },
   {
     "version": "1.20.117",
     "date": "2026-08-06T01:05:58.683Z",