@blumintinc/eslint-plugin-blumint 1.20.102 → 1.20.103

package/README.md

@@ -256,7 +256,7 @@ full closed loop is documented in agora's `.claude/skills/eslint-autonomy/SKILL.
 | [prevent-children-clobber](docs/rules/prevent-children-clobber.md)                                           | Prevent JSX spreads from silently discarding props.children                                                                                                                                                                                                                                                                                                                                      | ✅  |    |    |    |    |
 | [react-memoize-literals](docs/rules/react-memoize-literals.md)                                               | Detect object, array, and function literals created in React components or hooks that create new references every render. Prefer memoized values (useMemo/useCallback) or module-level constants to keep referential stability.                                                                                                                                                                  | ✅  |    |    | 💡 |    |
 | [react-usememo-should-be-component](docs/rules/react-usememo-should-be-component.md)                         | Enforce that useMemo hooks explicitly returning JSX should be abstracted into separate React components                                                                                                                                                                                                                                                                                          | ✅  |    |    |    |    |
-| [require-dynamic-firebase-imports](docs/rules/require-dynamic-firebase-imports.md)                           | Enforce dynamic imports for Firebase dependencies                                                                                                                                                                                                                                                                                                                                                | ✅  |    | 🔧 |    |    |
+| [require-dynamic-firebase-imports](docs/rules/require-dynamic-firebase-imports.md)                           | Enforce dynamic imports for Firebase dependencies                                                                                                                                                                                                                                                                                                                                                | ✅  |    |    |    |    |
 | [require-hooks-default-params](docs/rules/require-hooks-default-params.md)                                   | Enforce React hooks with optional parameters to default to an empty object                                                                                                                                                                                                                                                                                                                       | ✅  |    | 🔧 |    |    |
 | [require-https-error](docs/rules/require-https-error.md)                                                     | Enforce using proprietary HttpsError instead of throw new Error or firebase-admin HttpsError in functions/src                                                                                                                                                                                                                                                                                    | ✅  |    |    |    |    |
 | [require-https-error-cause](docs/rules/require-https-error-cause.md)                                         | Ensure HttpsError calls inside catch blocks pass the caught error as the fourth "cause" argument to preserve stack traces for monitoring.                                                                                                                                                                                                                                                        | ✅  |    |    |    |    |

package/lib/index.js

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

package/lib/rules/require-dynamic-firebase-imports.d.ts

@@ -1,6 +1,6 @@
-import { TSESLint, TSESTree } from '@typescript-eslint/utils';
+import { TSESTree } from '@typescript-eslint/utils';
 export declare const RULE_NAME = "require-dynamic-firebase-imports";
-declare const _default: TSESLint.RuleModule<"requireDynamicImport", never[], {
+declare const _default: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"requireDynamicImport", never[], {
     ImportDeclaration(node: TSESTree.ImportDeclaration): void;
 }>;
 export default _default;

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

@@ -3,79 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RULE_NAME = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
-const ASTHelpers_1 = require("../utils/ASTHelpers");
 exports.RULE_NAME = 'require-dynamic-firebase-imports';
-/**
- * A specifier is erased at compile time when either the whole statement is an
- * `import type` or the specifier carries an inline `type` marker. Only such a
- * specifier is interchangeable with the `import type` the fixer hoists.
- */
-const isErasableTypeSpecifier = (declaration, specifier) => declaration.importKind === 'type' || specifier.importKind === 'type';
-/**
- * Whether `specifier` binds the same local name to the same export of
- * `importSource` in type position as `target` — i.e. whether it is exactly the
- * binding the hoisted `import type` would introduce.
- */
-const bindsSameTypeImport = (specifier, target, importSource) => {
-    if (specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier ||
-        specifier.local.name !== target.local.name ||
-        specifier.imported.name !== target.imported.name) {
-        return false;
-    }
-    const declaration = specifier.parent;
-    return (declaration?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
-        declaration.source.value === importSource &&
-        isErasableTypeSpecifier(declaration, specifier));
-};
-/**
- * Read the module-scope import state off `Program.body` rather than a traversal
- * flag: `--fix` runs multiple passes, and a sibling report in an earlier pass may
- * already have hoisted the same `import type`. A flag set by the
- * `ImportDeclaration` visitor also depends on source order, so it would be stale
- * for any import that precedes the one being rewritten.
- */
-const findHoistedTypeImport = (program, target, importSource) => {
-    for (const statement of program.body) {
-        if (statement.type !== utils_1.AST_NODE_TYPES.ImportDeclaration) {
-            continue;
-        }
-        const match = statement.specifiers.find((specifier) => bindsSameTypeImport(specifier, target, importSource));
-        if (match) {
-            return match;
-        }
-    }
-    return undefined;
-};
-/**
- * The binding that makes hoisting `target` unsafe, or `null` when the name is
- * free (or already bound to the very import being hoisted).
- *
- * Resolution walks the scope chain of the rewritten import instead of stopping
- * at module scope, because a narrower shadow raises no TypeScript diagnostic yet
- * silently binds the hoisted type to the wrong declaration. Each hop resolves a
- * single step further up: the rewritten statement binds its own inline `type`
- * specifier in the enclosing function scope, which would otherwise mask the
- * colliding declaration above it. Bindings without a definition are ambient
- * (TypeScript lib types, configured globals); a module-scope import legally
- * shadows those, so they are not collisions.
- */
-const findCollidingBinding = (scope, target, importSource) => {
-    let current = scope;
-    while (current) {
-        const existing = ASTHelpers_1.ASTHelpers.findVariableInScope(current, target.local.name);
-        if (!existing) {
-            return null;
-        }
-        if (existing.defs.length > 0) {
-            const bindsTheDesiredImport = existing.defs.every((def) => bindsSameTypeImport(def.node, target, importSource));
-            if (!bindsTheDesiredImport) {
-                return existing;
-            }
-        }
-        current = existing.scope.upper;
-    }
-    return null;
-};
 exports.default = (0, createRule_1.createRule)({
     name: exports.RULE_NAME,
     meta: {
@@ -84,7 +12,6 @@ exports.default = (0, createRule_1.createRule)({
             description: 'Enforce dynamic imports for Firebase dependencies',
             recommended: 'error',
         },
-        fixable: 'code',
         schema: [],
         messages: {
             requireDynamicImport: 'Static Firebase import from "{{importSource}}" keeps the Firebase SDK in the initial bundle and blocks route-level code splitting. Use an `await import(\'{{importSource}}\')` dynamic import so Firebase loads only on the code path that needs it; type-only imports remain allowed.',
@@ -96,64 +23,8 @@ exports.default = (0, createRule_1.createRule)({
             return (source.startsWith('firebase/') ||
                 source.includes('config/firebase-client'));
         };
-        /**
-         * `await import()` is only valid inside an async function. Rewriting a
-         * module-scope import would introduce top-level await, silently converting
-         * a synchronous module into an async one (and failing outright on build
-         * targets without top-level await support) — so those sites are reported
-         * without a fix.
-         */
-        const isInsideAsyncFunction = (node) => {
-            let current = node.parent;
-            while (current) {
-                if (current.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
-                    current.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
-                    current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
-                    // The nearest enclosing function decides await validity; an async
-                    // ancestor beyond a sync function cannot host the await.
-                    return current.async;
-                }
-                current = current.parent;
-            }
-            return false;
-        };
         const isTypeOnlySpecifier = (spec) => spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
             spec.importKind === 'type';
-        const buildDynamicImport = (importSource, valueSpecifiers) => {
-            if (valueSpecifiers.length === 0) {
-                // Side-effect imports have no bindings to destructure.
-                return `await import('${importSource}');`;
-            }
-            const namespaceSpecifier = valueSpecifiers.find((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier);
-            const defaultSpecifier = valueSpecifiers.find((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier);
-            const namedSpecifiers = valueSpecifiers.filter((spec) => spec.type === utils_1.AST_NODE_TYPES.ImportSpecifier);
-            if (namespaceSpecifier) {
-                // The promise resolved by `import()` IS the module namespace object,
-                // so the `* as ns` binding maps directly onto it.
-                const namespaceDeclaration = `const ${namespaceSpecifier.local.name} = await import('${importSource}');`;
-                if (defaultSpecifier) {
-                    return `${namespaceDeclaration} const ${defaultSpecifier.local.name} = ${namespaceSpecifier.local.name}.default;`;
-                }
-                return namespaceDeclaration;
-            }
-            const destructuredNames = namedSpecifiers.map((spec) => spec.imported.name === spec.local.name
-                ? spec.local.name
-                : `${spec.imported.name}: ${spec.local.name}`);
-            if (defaultSpecifier) {
-                if (destructuredNames.length === 0) {
-                    return `const ${defaultSpecifier.local.name} = (await import('${importSource}')).default;`;
-                }
-                // The namespace object exposes the default export under `default`.
-                return `const { default: ${defaultSpecifier.local.name}, ${destructuredNames.join(', ')} } = await import('${importSource}');`;
-            }
-            return `const { ${destructuredNames.join(', ')} } = await import('${importSource}');`;
-        };
-        const buildStaticTypeImport = (importSource, typeSpecifiers) => {
-            const names = typeSpecifiers.map((spec) => spec.imported.name === spec.local.name
-                ? spec.local.name
-                : `${spec.imported.name} as ${spec.local.name}`);
-            return `import type { ${names.join(', ')} } from '${importSource}';\n`;
-        };
         return {
             ImportDeclaration(node) {
                 const importSource = node.source.value;
@@ -166,50 +37,23 @@ exports.default = (0, createRule_1.createRule)({
                 if (node.importKind === 'type') {
                     return;
                 }
-                const typeSpecifiers = node.specifiers.filter(isTypeOnlySpecifier);
                 const valueSpecifiers = node.specifiers.filter((spec) => !isTypeOnlySpecifier(spec));
                 // Inline `type` markers on every specifier make the whole statement
                 // erasable, exactly like `import type` — nothing to report.
                 if (node.specifiers.length > 0 && valueSpecifiers.length === 0) {
                     return;
                 }
+                // The rule is report-only. A static `import` declaration is legal only
+                // at the top level of a module or namespace, so every reported site is
+                // at module scope, where the `await import()` replacement would
+                // introduce top-level await — silently converting a synchronous module
+                // into an async one and breaking build targets that lack it. The
+                // author must instead move the import into the async code path that
+                // needs it, which is a restructuring no autofix can make safely.
                 context.report({
                     node,
                     messageId: 'requireDynamicImport',
                     data: { importSource },
-                    fix(fixer) {
-                        if (!isInsideAsyncFunction(node)) {
-                            return null;
-                        }
-                        // Type specifiers must not travel into the runtime destructuring:
-                        // they have no runtime value, and dropping the `type` marker turns
-                        // type references into dangling value bindings. They hoist into a
-                        // static `import type` at module scope, which is erased at compile
-                        // time.
-                        const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
-                        const program = context.getSourceCode().ast;
-                        const specifiersToHoist = [];
-                        for (const specifier of typeSpecifiers) {
-                            if (findCollidingBinding(scope, specifier, importSource)) {
-                                // Declining the whole fix keeps the file compiling: applying
-                                // the dynamic import while skipping a colliding hoist would
-                                // strand the type reference (TS2749) instead of duplicating an
-                                // identifier (TS2440/TS2300). The report stands so the author
-                                // resolves the name clash deliberately.
-                                return null;
-                            }
-                            if (!findHoistedTypeImport(program, specifier, importSource)) {
-                                specifiersToHoist.push(specifier);
-                            }
-                        }
-                        const fixes = [
-                            fixer.replaceText(node, buildDynamicImport(importSource, valueSpecifiers)),
-                        ];
-                        if (specifiersToHoist.length > 0) {
-                            fixes.push(fixer.insertTextBeforeRange([0, 0], buildStaticTypeImport(importSource, specifiersToHoist)));
-                        }
-                        return fixes;
-                    },
                 });
             },
         };

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

@@ -505,6 +505,7 @@ const DEFAULT_BINDING = 'default';
  */
 const moduleResolutionCache = new Map();
 const propLessBindingCache = new Map();
+const unionMemberCache = new Map();
 /**
  * Stat a candidate path, returning its identity stamp when it is a file. The
  * single stat both resolves existence and stamps the file, so proving a child
@@ -902,6 +903,170 @@ function getDependencyPropsSourceType(program, depName) {
     }
     return null;
 }
+/**
+ * Name one arm of a union, and flatten whatever the arm turns out to be.
+ *
+ * Only an arm spelled as a type *reference* yields a name: an inline object arm
+ * has no name a parent could compose with, and an intersection arm's members
+ * describe a fragment of the arm rather than the arm itself. A named arm is
+ * 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) {
+    if (arm.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+        for (const nested of arm.types) {
+            collectUnionArmNames(nested, program, seenAliases, into);
+        }
+        return;
+    }
+    if (arm.type !== utils_1.AST_NODE_TYPES.TSTypeReference) {
+        return;
+    }
+    const name = getTypeReferenceName(arm);
+    if (name === 'Readonly') {
+        // 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);
+        }
+        return;
+    }
+    if (!name || seenAliases.has(name)) {
+        return;
+    }
+    into.add(name);
+    const alias = findPropsTypeAliasByName(program, name);
+    if (alias) {
+        const nextSeen = new Set(seenAliases);
+        nextSeen.add(name);
+        collectUnionArmNames(alias.typeAnnotation, program, nextSeen, into);
+    }
+}
+/**
+ * Collect the named arms of a props type that resolves to a union, following
+ * `Readonly<...>` wrappers and named-alias indirection within `program` to reach
+ * it. A props type that is not a union contributes nothing, so a single-shape
+ * child keeps demanding composition with its own name.
+ *
+ * Resolving *to* the union never names anything on the way: only an arm of a
+ * 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()) {
+    if (!typeNode) {
+        return into;
+    }
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+        for (const arm of typeNode.types) {
+            collectUnionArmNames(arm, program, seenAliases, into);
+        }
+        return into;
+    }
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+        const name = getTypeReferenceName(typeNode);
+        if (name === 'Readonly') {
+            const inner = typeNode.typeParameters?.params[0];
+            if (inner) {
+                collectUnionMemberNames(inner, program, seenAliases, into);
+            }
+            return into;
+        }
+        if (name && !seenAliases.has(name)) {
+            const alias = findPropsTypeAliasByName(program, name);
+            if (alias) {
+                const nextSeen = new Set(seenAliases);
+                nextSeen.add(name);
+                collectUnionMemberNames(alias.typeAnnotation, program, nextSeen, into);
+            }
+        }
+    }
+    return into;
+}
+/**
+ * The props type node a module exports alongside `binding`: its
+ * `{Binding}Props` alias when one exists, otherwise the exported component's
+ * own first-parameter annotation. Mirrors getDependencyPropsSourceType for a
+ * foreign program, resolving the export's local name first so
+ * `const X = …; export { X as Y }` reads X's props type.
+ */
+function getExportedPropsSourceType(program, binding) {
+    if (binding === DEFAULT_BINDING) {
+        const fn = findDefaultExportFunction(program);
+        return fn ? getFirstParamTypeNode(fn) : null;
+    }
+    const local = findExportedLocalName(program, binding);
+    return local === null ? null : getDependencyPropsSourceType(program, local);
+}
+/**
+ * The union arms of a dependency's props type as declared in the sibling module
+ * it is imported from. Resolution mirrors isPropLessImportedComponent — a
+ * relative specifier, a file that exists on disk, no shadowing declaration
+ * inside the rendering component — so anything the parse cannot decide yields
+ * no members and the composition requirement stands.
+ */
+function getImportedDependencyUnionMembers(program, localName, filename, componentRoot, cwd) {
+    const relativeImport = findRelativeImport(program, localName);
+    if (!relativeImport) {
+        return [];
+    }
+    if (isNameDeclaredWithin(componentRoot, localName)) {
+        return [];
+    }
+    try {
+        const absolute = path_1.default.isAbsolute(filename)
+            ? filename
+            : path_1.default.resolve(cwd, filename);
+        const resolved = resolveRelativeModule(path_1.default.dirname(absolute), relativeImport.source);
+        if (!resolved) {
+            return [];
+        }
+        const cacheKey = JSON.stringify([
+            resolved.filePath,
+            relativeImport.binding,
+        ]);
+        const cached = unionMemberCache.get(cacheKey);
+        if (cached !== undefined &&
+            cached.mtimeMs === resolved.mtimeMs &&
+            cached.size === resolved.size) {
+            return cached.members;
+        }
+        const childProgram = parseModuleProgram(resolved.filePath);
+        const members = childProgram
+            ? Array.from(collectUnionMemberNames(getExportedPropsSourceType(childProgram, relativeImport.binding), childProgram))
+            : [];
+        unionMemberCache.set(cacheKey, {
+            mtimeMs: resolved.mtimeMs,
+            size: resolved.size,
+            members,
+        });
+        return members;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Every name the file under lint can use to reference an imported type: the
+ * exported name itself plus each `import { Exported as Local }` rename of it.
+ * A union member declared in a sibling module is written with the local
+ * spelling at the composition site.
+ */
+function collectImportSpellings(program, importedName) {
+    const spellings = [importedName];
+    for (const stmt of program.body) {
+        if (stmt.type !== utils_1.AST_NODE_TYPES.ImportDeclaration)
+            continue;
+        for (const specifier of stmt.specifiers) {
+            if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                specifier.imported.name === importedName &&
+                specifier.local.name !== importedName) {
+                spellings.push(specifier.local.name);
+            }
+        }
+    }
+    return spellings;
+}
 exports.requirePropsComposition = (0, createRule_1.createRule)({
     name: 'require-props-composition',
     meta: {
@@ -1019,6 +1184,25 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
                 checkComponentWithProgram(componentName, node, node.id, prog);
             },
         };
+        /**
+         * Whether the parent's props type composes with a member of `dep`'s props
+         * union. Both spellings the member can take are tried: the in-file
+         * declaration, and the sibling module's export (under the exported name and
+         * under any local rename the parent imports it as).
+         *
+         * A dependency whose props type is not a union yields no members, so this
+         * never credits a parent that composes with nothing.
+         */
+        function composesWithUnionMember(dep, propsTypeNode, prog, componentRoot) {
+            const localMembers = collectUnionMemberNames(getDependencyPropsSourceType(prog, dep), prog);
+            for (const member of localMembers) {
+                if (typeNodeComposesWithProps(propsTypeNode, member, prog)) {
+                    return true;
+                }
+            }
+            const importedMembers = getImportedDependencyUnionMembers(prog, dep, rawFilename, componentRoot, cwd);
+            return importedMembers.some((member) => collectImportSpellings(prog, member).some((spelling) => typeNodeComposesWithProps(propsTypeNode, spelling, prog)));
+        }
         function checkComponentWithProgram(componentName, funcNode, reportNode, prog) {
             // Collect all JSX element names used in the component body
             const body = funcNode.body ?? funcNode;
@@ -1084,6 +1268,25 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
                     missingComposition.push(dep);
                 }
             }
+            // A child whose props type is a union is composed by composing with any
+            // one of its MEMBERS: `Pick<ChipToggleProps, 'label'>` inherits exactly
+            // the surface the child accepts on that arm, so the DRY guarantee holds
+            // just as it does for the union alias itself. This mirrors on the child
+            // side the `.some` rule issue #1343 established on the parent side.
+            //
+            // Deferred behind the whole cheap pass because resolving a sibling
+            // module's members reads it off disk: a file that already composes never
+            // pays for it.
+            if (missingComposition.length > 0 &&
+                (requireAllDependencies || composedWith.size === 0)) {
+                for (let index = missingComposition.length - 1; index >= 0; index--) {
+                    const dep = missingComposition[index];
+                    if (composesWithUnionMember(dep, propsTypeNode, prog, funcNode)) {
+                        composedWith.add(dep);
+                        missingComposition.splice(index, 1);
+                    }
+                }
+            }
             if (!requireAllDependencies) {
                 // Only flag when NO dependency has composition
                 if (composedWith.size > 0) {

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,26 @@
 [
+  {
+    "version": "1.20.103",
+    "date": "2026-08-04T18:19:46.054Z",
+    "rules": [
+      {
+        "name": "require-dynamic-firebase-imports",
+        "changeType": "fix",
+        "issues": [
+          1708
+        ],
+        "summary": "drop the unreachable autofix declaration (closes #1708)"
+      },
+      {
+        "name": "require-props-composition",
+        "changeType": "fix",
+        "issues": [
+          1709
+        ],
+        "summary": "credit composition with a member of the child's props union (closes #1709)"
+      }
+    ]
+  },
   {
     "version": "1.20.102",
     "date": "2026-08-04T17:20:02.924Z",