@blumintinc/eslint-plugin-blumint 1.20.154 → 1.20.155

package/lib/index.js

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

package/lib/rules/no-explicit-return-type.js

@@ -569,32 +569,164 @@ function isOverloadedFunction(node) {
     }
     return false;
 }
-function isOverloadedTsDeclareFunction(node) {
+/**
+ * The statement list that directly holds `node`, looking through `export`.
+ *
+ * Overload signatures and their implementation are siblings of one statement
+ * list — an overload set cannot span containers — so this is the only list worth
+ * reading. Walking outward instead would let a same-named function in an
+ * enclosing scope answer for one it cannot overload.
+ */
+function siblingStatementsOf(node) {
+    const parent = node.parent;
+    if (!parent)
+        return undefined;
+    const container = parent.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+        parent.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration
+        ? parent.parent
+        : parent;
+    return container ? (0, lexicalScope_1.statementsOf)(container) : undefined;
+}
+const EMPTY_OVERLOAD_SET = { signatures: 0, implementations: 0 };
+/**
+ * How many declaration-only signatures and how many implementations the
+ * container holding `node` declares under `node`'s own name, `node` included.
+ *
+ * Every statement container is read, not just `Program` and `TSModuleBlock`: a
+ * function body, a bare block and a `switch` case each bind a name just as
+ * effectively, so reading only the top level makes the DEPTH of an overload set
+ * decide whether it exists (the same defect as #1771).
+ */
+function overloadSetOf(node) {
     const functionName = node.id?.name;
     if (!functionName)
+        return EMPTY_OVERLOAD_SET;
+    const statements = siblingStatementsOf(node);
+    if (!statements)
+        return EMPTY_OVERLOAD_SET;
+    let signatures = 0;
+    let implementations = 0;
+    for (const statement of statements) {
+        // `export function f(...)` is the same declaration one AST node deeper, and
+        // an overload set may export some of its members and not others.
+        const declaration = (0, lexicalScope_1.declarationOf)(statement);
+        if (declaration.type !== utils_1.AST_NODE_TYPES.TSDeclareFunction &&
+            declaration.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+            continue;
+        }
+        if (declaration.id?.name !== functionName)
+            continue;
+        if (declaration.type === utils_1.AST_NODE_TYPES.TSDeclareFunction ||
+            !declaration.body) {
+            signatures += 1;
+        }
+        else {
+            implementations += 1;
+        }
+    }
+    return { signatures, implementations };
+}
+/**
+ * True when `node` is the IMPLEMENTATION of an overload set — a function with a
+ * body whose container also declares the same name as one or more
+ * declaration-only signatures.
+ *
+ * Its annotation is not a restatement of what the body returns: TypeScript
+ * checks each overload signature against the IMPLEMENTATION SIGNATURE, so the
+ * annotation is what the overloads are measured against. Inference yields the
+ * body's own type, which need not accept them — stripping `: void | string`
+ * from `function get(param?: string): void | string {}` infers `void` and makes
+ * the `: string` overload above it TS2394 (#2019).
+ *
+ * This carve-out ignores `allowOverloadedFunctions`. That option governs the
+ * declaration-only signatures, whose annotations are mandatory but carry no
+ * fixer, so reporting them costs nothing but a message. Here the report ships a
+ * fix that does not compile, which no option may ask for.
+ */
+function isOverloadImplementation(node) {
+    if (!node.body)
         return false;
-    let container = node.parent;
-    while (container) {
-        if (container.type === utils_1.AST_NODE_TYPES.Program ||
-            container.type === utils_1.AST_NODE_TYPES.TSModuleBlock) {
-            const declarations = container.body
-                .map((statement) => {
-                if (statement.type === utils_1.AST_NODE_TYPES.TSDeclareFunction) {
-                    return statement;
-                }
-                if (statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
-                    statement.declaration?.type === utils_1.AST_NODE_TYPES.TSDeclareFunction) {
-                    return statement.declaration;
-                }
-                return undefined;
-            })
-                .filter((value) => Boolean(value?.id?.name))
-                .filter((decl) => decl.id.name === functionName);
-            return declarations.length > 1;
+    return overloadSetOf(node).signatures > 0;
+}
+/**
+ * True when `node` is a declaration-only signature that belongs to an overload
+ * set: another signature declares the same name, or an implementation below it
+ * does. A lone `declare function f(): number;` overloads nothing, so it stays
+ * reportable.
+ */
+function isOverloadedTsDeclareFunction(node) {
+    const { signatures, implementations } = overloadSetOf(node);
+    return signatures > 1 || implementations > 0;
+}
+/**
+ * A method's identity inside its class body. Overloads agree on all three
+ * components; `static f` and `f` merely spell the same name, and a computed key
+ * names nothing resolvable, so it yields nothing. The separator keeps a private
+ * `#log` from colliding with a string key `'#log'`.
+ */
+function methodIdentityOf(node) {
+    if (node.computed)
+        return undefined;
+    if (node.key.type === utils_1.AST_NODE_TYPES.PrivateIdentifier) {
+        return `${node.static}\u0000private\u0000${node.key.name}`;
+    }
+    if (node.key.type !== utils_1.AST_NODE_TYPES.Identifier &&
+        node.key.type !== utils_1.AST_NODE_TYPES.Literal) {
+        return undefined;
+    }
+    const name = getNameFromIdentifierOrLiteral(node.key);
+    return name === undefined
+        ? undefined
+        : `${node.static}\u0000public\u0000${name}`;
+}
+/**
+ * The overload set a class method belongs to, counted over the members of its
+ * own class body. A member without a body is an overload signature
+ * (`TSEmptyBodyFunctionExpression`); the one member with a body is the
+ * implementation.
+ */
+function classOverloadSetOf(node) {
+    const identity = methodIdentityOf(node);
+    const classBody = node.parent;
+    if (!identity || classBody?.type !== utils_1.AST_NODE_TYPES.ClassBody) {
+        return EMPTY_OVERLOAD_SET;
+    }
+    let signatures = 0;
+    let implementations = 0;
+    for (const member of classBody.body) {
+        if (member.type !== utils_1.AST_NODE_TYPES.MethodDefinition)
+            continue;
+        if (methodIdentityOf(member) !== identity)
+            continue;
+        if (member.value.body) {
+            implementations += 1;
+        }
+        else {
+            signatures += 1;
         }
-        container = container.parent;
     }
-    return false;
+    return { signatures, implementations };
+}
+/**
+ * True when the method is the implementation of an overloaded class method, for
+ * the reason {@link isOverloadImplementation} gives — a class overload set is
+ * checked exactly as a function one is (#2019).
+ */
+function isOverloadImplementationMethod(node) {
+    if (!node.value.body)
+        return false;
+    return classOverloadSetOf(node).signatures > 0;
+}
+/**
+ * True when the method is a declaration-only overload signature. A body-less
+ * method is legal only as part of an overload set, so it is exempt whenever the
+ * set holds anything else at all.
+ */
+function isOverloadedClassMethodSignature(node) {
+    if (node.value.body)
+        return false;
+    const { signatures, implementations } = classOverloadSetOf(node);
+    return signatures > 1 || implementations > 0;
 }
 function isInterfaceOrAbstractMethodSignature(node) {
     if (node.type === utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition)
@@ -1233,6 +1365,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
                     isDecoratorFactory(node, returnType) ||
+                    isOverloadImplementation(node) ||
                     (mergedOptions.allowRecursiveFunctions &&
                         isRecursiveFunction(node)) ||
                     isReturnTypeRequiredByRecursion(node)) {
@@ -1292,6 +1425,9 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReadonlyWideningReturnType(returnType) ||
                     isAllowedVoidReturnType(returnType) ||
                     isDecoratorFactory(node, returnType) ||
+                    isOverloadImplementationMethod(node) ||
+                    (mergedOptions.allowOverloadedFunctions &&
+                        isOverloadedClassMethodSignature(node)) ||
                     (mergedOptions.allowAbstractMethodSignatures &&
                         isInterfaceOrAbstractMethodSignature(node)) ||
                     isReturnTypeRequiredByRecursion(node)) {

package/lib/rules/prefer-union-from-const-array.js

@@ -34,6 +34,46 @@ function isStringLiteralType(member) {
     const { literal } = member;
     return (literal.type === utils_1.AST_NODE_TYPES.Literal && typeof literal.value === 'string');
 }
+/**
+ * A declaration file is ambient in its entirety, so a declaration in one is
+ * subject to the ambient restriction even without an explicit `declare`.
+ */
+const DECLARATION_FILE = /\.d\.[cm]?ts$/i;
+/**
+ * An ambient context accepts only a string, numeric or literal-enum `const`
+ * initializer (TS1254), so the derived `as const` array cannot be emitted there
+ * at all — `as const` or not, an array literal is rejected. Declining is the
+ * remedy rather than a different rewrite, because no legal rewrite exists in
+ * that position: the rule asks for importable runtime values and an ambient
+ * declaration is precisely the promise that no runtime value is emitted.
+ *
+ * `declare` on the OUTERMOST module declaration makes every level nested below
+ * it ambient too, so the whole ancestor chain is walked rather than just the
+ * enclosing block. A module named by a string literal (`module 'x' {}`) and a
+ * `global {}` augmentation are ambient by construction, with or without the
+ * modifier.
+ */
+function isInAmbientContext(node, filename) {
+    if (DECLARATION_FILE.test(filename)) {
+        return true;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&
+        node.declare === true) {
+        return true;
+    }
+    let current = node.parent;
+    while (current) {
+        if (current.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration) {
+            if (current.declare === true ||
+                current.global === true ||
+                current.id.type === utils_1.AST_NODE_TYPES.Literal) {
+                return true;
+            }
+        }
+        current = current.parent;
+    }
+    return false;
+}
 /**
  * Walk the scope chain upward collecting declared variable names. Used to skip
  * the autofix (report-only) when the derived `{TYPE}_VALUES` name is already
@@ -154,6 +194,9 @@ exports.preferUnionFromConstArray = (0, createRule_1.createRule)({
                 if (!members.every(isStringLiteralType)) {
                     return;
                 }
+                if (isInAmbientContext(node, context.getFilename())) {
+                    return;
+                }
                 const typeName = node.id.name;
                 const constName = `${toUpperSnake(typeName)}_VALUES`;
                 // The type alias is exported when wrapped in `export type X = ...`

package/lib/rules/require-image-optimized.js

@@ -62,6 +62,49 @@ const isInsideComponentMock = (node, componentModule) => {
     }
     return false;
 };
+/**
+ * Name a declaration binds, for the forms a component is declared under:
+ * `const ImageOptimized = ...` (including `memo(...)`/`forwardRef(...)` around
+ * the body), `function ImageOptimized()` and `class ImageOptimized`. Anything
+ * else — an object property, a parameter — binds no declaration name the
+ * wrapper can be identified by, and treating it as one would exempt a mock
+ * factory keyed by the component name whatever module it stands in for.
+ */
+const declaredNameOf = (node) => {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.VariableDeclarator:
+            return node.id.type === utils_1.AST_NODE_TYPES.Identifier ? node.id.name : null;
+        case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+        case utils_1.AST_NODE_TYPES.FunctionExpression:
+        case utils_1.AST_NODE_TYPES.ClassDeclaration:
+        case utils_1.AST_NODE_TYPES.ClassExpression:
+            return node.id ? node.id.name : null;
+        default:
+            return null;
+    }
+};
+/**
+ * Names each local binding is exported under, so a wrapper declared as
+ * `Picture` and shipped as `export { Picture as ImageOptimized }` is still
+ * recognized as the component's own definition. A specifier carrying a `from`
+ * clause re-exports another module's binding and declares nothing here.
+ */
+const exportedNamesByLocal = (program) => {
+    const exported = new Map();
+    for (const statement of program.body) {
+        if (statement.type !== utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+            statement.source ||
+            statement.exportKind === 'type') {
+            continue;
+        }
+        for (const specifier of statement.specifiers) {
+            const names = exported.get(specifier.local.name) ?? new Set();
+            names.add(specifier.exported.name);
+            exported.set(specifier.local.name, names);
+        }
+    }
+    return exported;
+};
 /**
  * A type-only specifier binds no value: it renders nothing, so it neither
  * bypasses the optimization pipeline nor can back a fix. The modifier lives
@@ -219,6 +262,40 @@ module.exports = (0, createRule_1.createRule)({
          * rule exists to centralize, not a violation of it.
          */
         const isComponentImplementationFile = moduleNameOf(context.getFilename()) === componentModule;
+        /**
+         * The wrapper is identified by the name the fixer would emit and by its
+         * module's name, which a component module's export shares by convention.
+         * Matching is exact so a distinct component whose name merely starts with
+         * it (`ImageOptimizedGallery`) stays reportable.
+         */
+        const isComponentName = (name) => name === COMPONENT_NAME || name === componentModule;
+        const exportedNames = exportedNamesByLocal(sourceCode.ast);
+        const definesComponent = (name) => {
+            if (isComponentName(name)) {
+                return true;
+            }
+            const aliases = exportedNames.get(name);
+            return !!aliases && [...aliases].some(isComponentName);
+        };
+        /**
+         * Whether the element sits inside the declaration of the component the fix
+         * points at. That declaration renders the image primitive by definition, so
+         * swapping it for the component makes the wrapper render itself: unbounded
+         * recursion, and a type error too, since the wrapper forwards only the
+         * props it destructured. The whole ancestry is walked because a helper
+         * nested inside the declaration is part of that implementation as well.
+         */
+        const isInsideComponentDefinition = (node) => {
+            let current = node.parent;
+            while (current) {
+                const declared = declaredNameOf(current);
+                if (declared && definesComponent(declared)) {
+                    return true;
+                }
+                current = current.parent;
+            }
+            return false;
+        };
         return {
             // Handle JSX img elements
             JSXElement(node) {
@@ -228,7 +305,8 @@ module.exports = (0, createRule_1.createRule)({
                     return;
                 }
                 if (isComponentImplementationFile ||
-                    isInsideComponentMock(node, componentModule)) {
+                    isInsideComponentMock(node, componentModule) ||
+                    isInsideComponentDefinition(node)) {
                     return;
                 }
                 const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);

package/lib/utils/ASTHelpers.d.ts

@@ -85,6 +85,12 @@ export declare class ASTHelpers {
      * expression reads some other object.
      */
     private static classMemberNameReferencedBy;
+    /**
+     * The ECMA private names a class body declares, spelled as the graph spells
+     * them. A private name is scoped to the body that declares it, so this set
+     * is what an enclosing class must not mistake for its own members.
+     */
+    private static privateNamesDeclaredBy;
     private static walkChildNodes;
     static isNode(value: unknown): value is TSESTree.Node;
     static hasReturnStatement(node: TSESTree.Node): boolean;

package/lib/utils/ASTHelpers.js

@@ -423,7 +423,16 @@ class ASTHelpers {
             case 'ClassExpression': {
                 // Traversal continues so `<ClassName>.<member>` statics stay visible,
                 // but `this` no longer denotes the graphed instance.
-                this.walkChildNodes(node, className, false, dependencies);
+                const nested = [];
+                this.walkChildNodes(node, className, false, nested);
+                // A nested class body SHADOWS the private names it declares: its `#q`
+                // is a member of that class, distinct from an enclosing class's `#q`,
+                // so reads of it constrain the nested layout rather than this one.
+                // Private names the nested class does not declare still resolve
+                // outward, so only the declared ones are dropped. Filtering as the
+                // recursion unwinds composes across any depth of nesting.
+                const shadowed = this.privateNamesDeclaredBy(node);
+                dependencies.push(...nested.filter((name) => !shadowed.has(name)));
                 return;
             }
             case 'MemberExpression': {
@@ -447,6 +456,18 @@ class ASTHelpers {
      */
     static classMemberNameReferencedBy(node, className, isThisTheInstance) {
         const { object, property, computed } = node;
+        // A `#name` resolves LEXICALLY: it is a syntax error unless a class body
+        // enclosing the reference declares it, so the receiver it is read through
+        // cannot change which member it names. `other.#helper` and `this.#helper`
+        // reach the same member, which is why this branch precedes the receiver
+        // test that the dotted spellings need. Requiring `this`/<ClassName> here
+        // dropped the read a static initializer makes through another value of
+        // the same class, and with it the constraint that keeps the field's
+        // declaration above its reader (#2022). The `#` is part of the name so
+        // `#helper` and `helper` stay distinct members.
+        if (!computed && property?.type === 'PrivateIdentifier') {
+            return `#${property.name}`;
+        }
         const readsInstance = object?.type === 'ThisExpression' && isThisTheInstance;
         // An anonymous class expression has an empty name, which no identifier
         // can match.
@@ -457,12 +478,6 @@ class ASTHelpers {
         if (!computed && property?.type === 'Identifier') {
             return property.name;
         }
-        // `this.#helper` names a member as precisely as `this.helper` does, and it
-        // is the only spelling available for an ECMA private member. The `#` is
-        // part of the name so `#helper` and `helper` stay distinct members.
-        if (!computed && property?.type === 'PrivateIdentifier') {
-            return `#${property.name}`;
-        }
         // `this['helper']` names the member as precisely as `this.helper` does,
         // whereas `this[key]` names one only at runtime.
         if (computed &&
@@ -472,6 +487,25 @@ class ASTHelpers {
         }
         return null;
     }
+    /**
+     * The ECMA private names a class body declares, spelled as the graph spells
+     * them. A private name is scoped to the body that declares it, so this set
+     * is what an enclosing class must not mistake for its own members.
+     */
+    static privateNamesDeclaredBy(node) {
+        const names = new Set();
+        const members = node.body?.body;
+        if (!Array.isArray(members)) {
+            return names;
+        }
+        for (const member of members) {
+            const key = member?.key;
+            if (key?.type === 'PrivateIdentifier') {
+                names.add(`#${key.name}`);
+            }
+        }
+        return names;
+    }
     static walkChildNodes(node, className, isThisTheInstance, dependencies) {
         for (const [key, value] of Object.entries(node)) {
             if (ASTHelpers.NON_TRAVERSABLE_NODE_KEYS.has(key)) {

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,42 @@
 [
+  {
+    "version": "1.20.155",
+    "date": "2026-08-15T14:21:55.491Z",
+    "rules": [
+      {
+        "name": "class-methods-read-top-to-bottom",
+        "changeType": "fix",
+        "issues": [
+          2022
+        ],
+        "summary": "pin a # field by every read of it, not just this.#x (closes #2022)"
+      },
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          2019
+        ],
+        "summary": "spare the implementation signature of an overload set (closes #2019)"
+      },
+      {
+        "name": "prefer-union-from-const-array",
+        "changeType": "fix",
+        "issues": [
+          2020
+        ],
+        "summary": "decline in an ambient context, where no const array is legal (closes #2020)"
+      },
+      {
+        "name": "require-image-optimized",
+        "changeType": "fix",
+        "issues": [
+          2021
+        ],
+        "summary": "exempt the img inside ImageOptimized's own definition (closes #2021)"
+      }
+    ]
+  },
   {
     "version": "1.20.154",
     "date": "2026-08-15T03:47:51.570Z",